{ "openapi": "3.0.0", "info": { "title": "Archestra", "version": "v1.5.0-rc.41" }, "components": { "schemas": { "LogContentNotStoredInput": { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "log_content_policy" ] }, "isError": { "type": "boolean" }, "errorType": { "type": "string", "enum": [ "auth_required", "auth_expired", "assigned_credential_unavailable", "tool_state", "cancelled", "generic" ] }, "archestraExecutedAs": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] }, "ownerUserId": { "nullable": true, "type": "string" }, "ownerName": { "nullable": true, "type": "string" } }, "required": [ "kind", "ownerUserId", "ownerName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "team" ] }, "teamId": { "type": "string" }, "teamName": { "nullable": true, "type": "string" } }, "required": [ "kind", "teamId", "teamName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "org" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idp_exchange" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idp_passthrough" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller_headers" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "platform" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false } ] } }, "required": [ "__redacted" ] }, "TextSearchLanguageInput": { "type": "string", "enum": [ "simple", "arabic", "armenian", "basque", "catalan", "danish", "dutch", "english", "finnish", "french", "german", "greek", "hindi", "hungarian", "indonesian", "irish", "italian", "lithuanian", "nepali", "norwegian", "portuguese", "romanian", "russian", "serbian", "spanish", "swedish", "tamil", "turkish", "yiddish" ] }, "ContextualRetrievalModeInput": { "type": "string", "enum": [ "disabled", "document", "chunk" ] }, "EmbeddingDimensionsInput": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "enum": [ 3072, 1536, 1408, 1024, 768, 384 ] }, "LocalConfigEnvironmentDefaultInput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "OpenAiChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ] }, "OpenAiChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ] }, "GeminiGenerateContentRequestInput": { "type": "object", "properties": { "contents": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the author of this content." }, "parts": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "text": { "type": "string" }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "text" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "inlineData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "data" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "inlineData" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionCall": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionCall" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "response": { "type": "object", "additionalProperties": {} }, "willContinue": { "type": "boolean" }, "scheduling": { "type": "string", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] } }, "required": [ "name", "response" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionResponse" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "fileData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "fileUri": { "type": "string" } }, "required": [ "fileUri" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "fileData" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "language": { "type": "string", "enum": [ "LANGUAGE_UNSPECIFIED", "PYTHON" ] }, "executableCode": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "language", "executableCode" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "codeExecutionResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "OUTCOME_UNSPECIFIED", "OUTCOME_OK", "OUTCOME_FAILED", "OUTCOME_DEADLINE_EXCEEDED" ], "description": "Outcome of the code execution." }, "output": { "type": "string" } }, "required": [ "outcome" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "codeExecutionResult" ] } ] } ], "description": "https://ai.google.dev/api/caching#Part" } } }, "required": [ "role", "parts" ], "description": "\nThe base structured datatype containing multi-part content of a message.\n\nA Content includes a role field designating the producer of the Content and a parts field containing multi-part data that contains the content of the message turn.\n\nhttps://ai.google.dev/api/caching#Content\n" }, "description": "The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like chat, this is a repeated field that contains the conversation history and the latest request" }, "tools": { "description": "A list of Tools the Model may use to generate the next response. A Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the Model. Supported Tools are Function and codeExecution. Refer to the Function calling and the Code execution guides to learn more.", "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } }, { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } ] }, "toolConfig": { "description": "Tool configuration for any Tool specified in the request.", "type": "object", "properties": { "functionCallingConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "ANY", "NONE" ] }, "allowedFunctionNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] } }, "required": [ "functionCallingConfig" ] }, "safetySettings": { "description": "A list of unique SafetySetting instances for blocking unsafe content.", "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "HARM_CATEGORY_UNSPECIFIED", "HARM_CATEGORY_DEROGATORY", "HARM_CATEGORY_TOXICITY", "HARM_CATEGORY_VIOLENCE", "HARM_CATEGORY_SEXUAL", "HARM_CATEGORY_MEDICAL", "HARM_CATEGORY_DANGEROUS", "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY" ], "description": "\n The category for this setting\n\n https://ai.google.dev/api/generate-content#v1beta.HarmCategory\n" }, "threshold": { "type": "string", "enum": [ "HARM_BLOCK_THRESHOLD_UNSPECIFIED", "BLOCK_LOW_AND_ABOVE", "BLOCK_MEDIUM_AND_ABOVE", "BLOCK_ONLY_HIGH", "BLOCK_NONE", "OFF" ], "description": "\n Controls the probability threshold at which harm is blocked.\n\n https://ai.google.dev/api/generate-content#HarmBlockThreshold\n " } }, "required": [ "category", "threshold" ], "description": "https://ai.google.dev/api/generate-content#v1beta.SafetySetting" } }, "systemInstruction": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } } }, "required": [ "parts" ], "description": "Developer set system instruction(s). Currently, text only." }, "generationConfig": { "type": "object", "properties": { "stopSequences": { "type": "array", "items": { "type": "string" } }, "responseMimeType": { "type": "string" }, "responseSchema": {}, "_responseJsonSchema": {}, "responseJsonSchema": {}, "responseModalities": { "type": "array", "items": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" } }, "candidateCount": { "type": "number" }, "maxOutputTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "topK": { "type": "number" }, "seed": { "type": "number" }, "presencePenalty": { "type": "number" }, "frequencyPenalty": { "type": "number" }, "responseLogprobs": { "type": "boolean" }, "logProbs": { "type": "number" }, "enableEnhancedCivicAnswers": { "type": "boolean" }, "speechConfig": {}, "thinkingConfig": {}, "imageConfig": {}, "mediaResolution": { "description": "https://ai.google.dev/api/generate-content#MediaResolution", "type": "string", "enum": [ "MEDIA_RESOLUTION_UNSPECIFIED", "MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH" ] } }, "description": "https://ai.google.dev/api/generate-content#v1beta.GenerationConfig" }, "cachedContent": { "description": "The name of the content cached to use as context to serve the prediction. Format: cachedContents/{cachedContent}", "type": "string" }, "config": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } }, { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } ] }, "toolConfig": { "description": "Tool configuration for any Tool specified in the request.", "type": "object", "properties": { "functionCallingConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "ANY", "NONE" ] }, "allowedFunctionNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ] } }, "required": [ "functionCallingConfig" ] } } } }, "required": [ "contents" ] }, "GeminiGenerateContentResponseInput": { "type": "object", "properties": { "candidates": { "description": "Candidate responses from the model", "type": "array", "items": { "type": "object", "properties": { "content": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the author of this content." }, "parts": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "text": { "type": "string" }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "text" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "inlineData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "data" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "inlineData" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionCall": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionCall" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "response": { "type": "object", "additionalProperties": {} }, "willContinue": { "type": "boolean" }, "scheduling": { "type": "string", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] } }, "required": [ "name", "response" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionResponse" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "fileData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "fileUri": { "type": "string" } }, "required": [ "fileUri" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "fileData" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "language": { "type": "string", "enum": [ "LANGUAGE_UNSPECIFIED", "PYTHON" ] }, "executableCode": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "language", "executableCode" ] }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "codeExecutionResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "OUTCOME_UNSPECIFIED", "OUTCOME_OK", "OUTCOME_FAILED", "OUTCOME_DEADLINE_EXCEEDED" ], "description": "Outcome of the code execution." }, "output": { "type": "string" } }, "required": [ "outcome" ] }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "codeExecutionResult" ] } ] } ], "description": "https://ai.google.dev/api/caching#Part" } } }, "required": [ "role", "parts" ], "description": "\nThe base structured datatype containing multi-part content of a message.\n\nA Content includes a role field designating the producer of the Content and a parts field containing multi-part data that contains the content of the message turn.\n\nhttps://ai.google.dev/api/caching#Content\n" }, "finishReason": { "description": "\n The reason why the model stopped generating tokens.\n\n If empty, the model has not stopped generating tokens.\n\n https://ai.google.dev/api/generate-content#FinishReason\n", "anyOf": [ { "type": "string", "enum": [ "FINISH_REASON_UNSPECIFIED", "STOP", "MAX_TOKENS", "SAFETY", "RECITATION", "LANGUAGE", "OTHER", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII", "MALFORMED_FUNCTION_CALL", "IMAGE_SAFETY", "IMAGE_PROHIBITED_CONTENT", "IMAGE_OTHER", "NO_IMAGE", "IMAGE_RECITATION", "UNEXPECTED_TOOL_CALL", "TOO_MANY_TOOL_CALLS" ] }, { "type": "string" } ] }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "HARM_CATEGORY_UNSPECIFIED", "HARM_CATEGORY_DEROGATORY", "HARM_CATEGORY_TOXICITY", "HARM_CATEGORY_VIOLENCE", "HARM_CATEGORY_SEXUAL", "HARM_CATEGORY_MEDICAL", "HARM_CATEGORY_DANGEROUS", "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY" ], "description": "\n The category for this setting\n\n https://ai.google.dev/api/generate-content#v1beta.HarmCategory\n" }, "probability": { "type": "string", "enum": [ "HARM_PROBABILITY_UNSPECIFIED", "NEGLIGIBLE", "LOW", "MEDIUM", "HIGH" ], "description": "https://ai.google.dev/api/generate-content#HarmProbability" }, "blocked": { "description": "Was this content blocked because of this rating?", "type": "boolean" } }, "required": [ "category", "probability" ], "description": "https://ai.google.dev/api/generate-content#v1beta.SafetyRating" } }, "citationMetadata": { "description": "https://ai.google.dev/api/generate-content#citationmetadata", "type": "object", "properties": { "citationSources": { "type": "array", "items": { "description": "https://ai.google.dev/api/generate-content#CitationSource", "type": "object", "properties": { "startIndex": { "type": "number" }, "endIndex": { "type": "number" }, "uri": { "type": "string" }, "license": { "type": "string" } } } } }, "required": [ "citationSources" ] }, "tokenCount": { "type": "number" }, "groundingAttributions": { "type": "array", "items": {} }, "groundingMetadata": {}, "avgLogprobs": { "type": "number" }, "logprobsResult": {}, "urlContextMetadata": {}, "index": { "description": "Index of the candidate in the list of response candidates.", "type": "number" }, "finishMessage": { "description": "Details the reason why the model stopped generating tokens. This is populated only when finishReason is set.", "type": "string" } }, "description": "https://ai.google.dev/api/generate-content#candidate" } }, "promptFeedback": { "description": "Returns the prompt's feedback related to the content filters", "type": "object", "properties": { "blockReason": { "description": "Specifies the reason why the prompt was blocked. https://ai.google.dev/api/generate-content#BlockReason", "anyOf": [ { "type": "string", "enum": [ "BLOCK_REASON_UNSPECIFIED", "SAFETY", "OTHER", "BLOCKLIST", "PROHIBITED_CONTENT", "IMAGE_SAFETY" ] }, { "type": "string" } ] }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "HARM_CATEGORY_UNSPECIFIED", "HARM_CATEGORY_DEROGATORY", "HARM_CATEGORY_TOXICITY", "HARM_CATEGORY_VIOLENCE", "HARM_CATEGORY_SEXUAL", "HARM_CATEGORY_MEDICAL", "HARM_CATEGORY_DANGEROUS", "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY" ], "description": "\n The category for this setting\n\n https://ai.google.dev/api/generate-content#v1beta.HarmCategory\n" }, "probability": { "type": "string", "enum": [ "HARM_PROBABILITY_UNSPECIFIED", "NEGLIGIBLE", "LOW", "MEDIUM", "HIGH" ], "description": "https://ai.google.dev/api/generate-content#HarmProbability" }, "blocked": { "description": "Was this content blocked because of this rating?", "type": "boolean" } }, "required": [ "category", "probability" ], "description": "https://ai.google.dev/api/generate-content#v1beta.SafetyRating" } } } }, "usageMetadata": { "description": "Metadata on the generation requests' token usage", "type": "object", "properties": { "trafficType": { "description": "Traffic tier that served the request.", "type": "string" }, "promptTokenCount": { "type": "number" }, "cachedContentTokenCount": { "type": "number" }, "candidatesTokenCount": { "type": "number" }, "toolUsePromptTokenCount": { "type": "number" }, "thoughtsTokenCount": { "type": "number" }, "totalTokenCount": { "type": "number" }, "promptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } }, "cacheTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } }, "candidatesTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } }, "toolUsePromptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } } } }, "modelVersion": { "description": "The model version used to generate the response.", "type": "string" }, "responseId": { "description": "The unique response ID.", "type": "string" } } }, "AnthropicMessagesRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" } }, "required": [ "model", "messages", "max_tokens" ], "additionalProperties": {} }, "AnthropicMessagesResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "citations": { "nullable": true, "type": "array", "items": {} }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "citations", "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": {} } ] } }, "model": { "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "stop_reason": { "nullable": true }, "stop_sequence": { "nullable": true, "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "cache_read_input_tokens": { "nullable": true, "type": "number" }, "cache_creation_input_tokens": { "nullable": true, "type": "number" }, "cache_creation": { "nullable": true, "type": "object", "properties": { "ephemeral_1h_input_tokens": { "nullable": true, "type": "number" }, "ephemeral_5m_input_tokens": { "nullable": true, "type": "number" } } } }, "required": [ "input_tokens", "output_tokens" ], "additionalProperties": {} } }, "required": [ "id", "content", "model", "role", "type", "usage" ], "additionalProperties": {} }, "CerebrasChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ] }, "CerebrasChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/Cerebras/cerebras-cloud-sdk-node/blob/main/src/resources/chat/completions.ts" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/Cerebras/cerebras-cloud-sdk-node/blob/main/src/resources/chat/completions.ts" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ] }, "CohereChatRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ] } }, "required": [ "type", "image_url" ] } ] } } ] } }, "required": [ "role", "content" ] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_result" ] }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "type", "tool_call_id", "content" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" } }, "required": [ "type", "thinking" ] }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] } } }, "required": [ "role" ] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system" ] }, "content": { "type": "string" } }, "required": [ "role", "content" ] }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "role", "tool_call_id", "content" ] } ] } }, "stream": { "type": "boolean" }, "temperature": { "type": "number" }, "max_tokens": { "type": "number" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ] } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } }, "tool_choice": { "type": "string", "enum": [ "REQUIRED", "NONE" ] }, "safety_mode": { "type": "string", "enum": [ "CONTEXTUAL", "STRICT", "OFF" ] }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object", "text" ] }, "json_schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ] }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "k": { "type": "number" }, "p": { "type": "number" }, "seed": { "type": "number" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "logprobs": { "type": "boolean" } }, "required": [ "model", "messages" ] }, "CohereChatResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_result" ] }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "type", "tool_call_id", "content" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" } }, "required": [ "type", "thinking" ] }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] } } }, "required": [ "role" ] }, "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "COMPLETE", "MAX_TOKENS", "STOP_SEQUENCE", "TOOL_CALL", "ERROR" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" } } }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" } } } } } }, "required": [ "id", "message", "finish_reason" ] }, "MistralChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ] }, "MistralChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "PerplexityChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" }, "stream_mode": { "type": "string", "enum": [ "full", "concise" ] } }, "required": [ "model", "messages" ] }, "PerplexityChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "GroqChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ] }, "GroqChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "OpenrouterChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ] } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ] } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ] } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ] } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ] }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ] } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ] } }, "required": [ "type" ], "additionalProperties": {} }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" }, "reasoning": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "effort": { "type": "string" }, "max_tokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "exclude": { "type": "boolean" } } } }, "required": [ "model", "messages" ] }, "OpenrouterChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "JevDecisionsRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ], "description": "The content the questions are about" }, "questions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Question kind: noul, choice, or score" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "criteria": {} }, "required": [ "type", "instructions", "criteria" ], "additionalProperties": {} }, "description": "Decision questions keyed by name" } }, "required": [ "model", "state", "questions" ], "additionalProperties": {} }, "JevDecisionsResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "answers": { "type": "object", "additionalProperties": {} }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cost": { "type": "number", "minimum": 0 } }, "additionalProperties": {} } }, "required": [ "answers" ], "additionalProperties": {} }, "VllmChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "A developer message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "A system message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "Image URL details" } }, "required": [ "type", "image_url" ], "description": "An image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_audio" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "Audio input details" } }, "required": [ "type", "input_audio" ], "description": "An audio content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "File details" } }, "required": [ "type", "file" ], "description": "A file content part" } ], "description": "A content part in a message" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "A user message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "A refusal content part" } } ] }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "Function call details" } }, "required": [ "id", "type", "function" ], "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } }, "reasoning": { "nullable": true, "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" } }, "required": [ "role" ], "description": "An assistant message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "Image URL details" } }, "required": [ "type", "image_url" ], "description": "An image content part" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "A tool result message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "A function result message (deprecated)" } ], "description": "A message in the conversation" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "description": "A function tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ] } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "A custom tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "A custom tool in the flat Responses-API shape (see the OpenAI provider's ResponsesStyleCustomToolSchema)" } ], "description": "A tool definition" } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model.\n auto: allows the model to pick from allowed tools or generate a message.\n required: requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "description": "A function tool definition" } } } }, "required": [ "mode", "tools" ], "description": "Allowed tools configuration" } }, "required": [ "type", "allowed_tools" ], "description": "Allowed tool choice configuration" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "Named function tool choice" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ] } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "A custom tool definition" } ], "description": "Tool choice option" }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "stream": { "nullable": true, "type": "boolean" }, "top_p": { "nullable": true, "type": "number" }, "top_k": { "nullable": true, "type": "number" }, "frequency_penalty": { "nullable": true, "type": "number" }, "presence_penalty": { "nullable": true, "type": "number" }, "repetition_penalty": { "nullable": true, "type": "number" }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "nullable": true, "type": "number" }, "n": { "nullable": true, "type": "number" }, "best_of": { "nullable": true, "type": "number" }, "logprobs": { "nullable": true, "type": "boolean" }, "top_logprobs": { "nullable": true, "type": "number" }, "chat_template_kwargs": { "type": "object", "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string" } }, "required": [ "model", "messages" ] }, "VllmChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "Function call details" } }, "required": [ "id", "type", "function" ], "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } }, "reasoning": { "nullable": true, "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" } }, "required": [ "role" ], "description": "The assistant message in the response" } }, "required": [ "finish_reason", "message" ], "description": "A choice in the chat completion response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": {}, "prompt_tokens_details": {} }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "Token usage statistics for the completion" } }, "required": [ "id", "choices", "created", "model", "object" ] }, "OllamaChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "A developer message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "A system message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "Image URL details" } }, "required": [ "type", "image_url" ], "description": "An image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_audio" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "Audio input details" } }, "required": [ "type", "input_audio" ], "description": "An audio content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "File details" } }, "required": [ "type", "file" ], "description": "A file content part" } ], "description": "A content part in a message" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "A user message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "A refusal content part" } } ] }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "Function call details" } }, "required": [ "id", "type", "function" ], "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } } }, "required": [ "role" ], "description": "An assistant message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "Image URL details" } }, "required": [ "type", "image_url" ], "description": "An image content part" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "A tool result message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "A function result message (deprecated)" } ], "description": "A message in the conversation" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "description": "A function tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ] } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "A custom tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "A custom tool in the flat Responses-API shape (see the OpenAI provider's ResponsesStyleCustomToolSchema)" } ], "description": "A tool definition" } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model.\n auto: allows the model to pick from allowed tools or generate a message.\n required: requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "description": "A function tool definition" } } } }, "required": [ "mode", "tools" ], "description": "Allowed tools configuration" } }, "required": [ "type", "allowed_tools" ], "description": "Allowed tool choice configuration" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "Named function tool choice" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ] } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "A custom tool definition" } ], "description": "Tool choice option" }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "stream": { "nullable": true, "type": "boolean" }, "top_p": { "nullable": true, "type": "number" }, "frequency_penalty": { "nullable": true, "type": "number" }, "presence_penalty": { "nullable": true, "type": "number" }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "nullable": true, "type": "number" }, "n": { "nullable": true, "type": "number" }, "reasoning_effort": { "nullable": true, "type": "string" } }, "required": [ "model", "messages" ] }, "OllamaChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "Function call details" } }, "required": [ "id", "type", "function" ], "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } } }, "required": [ "role" ], "description": "The assistant message in the response" } }, "required": [ "finish_reason", "message" ], "description": "A choice in the chat completion response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": {}, "prompt_tokens_details": {} }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "Token usage statistics for the completion" } }, "required": [ "id", "choices", "created", "model", "object" ] }, "OllamaNativeChatRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "thinking": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "tool_calls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "function": { "type": "object", "properties": { "index": { "type": "number" }, "name": { "type": "string" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "name", "arguments" ], "additionalProperties": {} } }, "required": [ "function" ], "additionalProperties": {} } }, "tool_name": { "type": "string" }, "tool_call_id": { "type": "string" } }, "required": [ "role" ], "additionalProperties": {} } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": {} } }, "required": [ "type", "function" ], "additionalProperties": {} } }, "format": {}, "options": { "type": "object", "properties": { "temperature": { "type": "number" }, "top_k": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "top_p": { "type": "number" }, "min_p": { "type": "number" }, "typical_p": { "type": "number" }, "seed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "repeat_penalty": { "type": "number" }, "repeat_last_n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "presence_penalty": { "type": "number" }, "frequency_penalty": { "type": "number" }, "stop": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 256 } }, "num_keep": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "num_ctx": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "num_predict": { "type": "integer", "minimum": -2, "maximum": 9007199254740991 } } }, "stream": { "nullable": true, "type": "boolean" }, "keep_alive": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "think": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "temperature": { "nullable": true, "type": "number" }, "top_p": { "nullable": true, "type": "number" }, "max_output_tokens": { "nullable": true, "type": "number" }, "truncate": { "type": "boolean" }, "shift": { "type": "boolean" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, "OllamaNativeChatResponseInput": { "type": "object", "properties": { "model": { "type": "string" }, "created_at": { "type": "string" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "thinking": { "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "function": { "type": "object", "properties": { "index": { "type": "number" }, "name": { "type": "string" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "name", "arguments" ], "additionalProperties": {} } }, "required": [ "function" ], "additionalProperties": {} } } }, "required": [ "role" ], "additionalProperties": {} }, "done": { "type": "boolean" }, "done_reason": { "type": "string" }, "total_duration": { "type": "number" }, "load_duration": { "type": "number" }, "prompt_eval_count": { "type": "number" }, "prompt_eval_duration": { "type": "number" }, "eval_count": { "type": "number" }, "eval_duration": { "type": "number" } }, "required": [ "model", "message", "done" ], "additionalProperties": {} }, "ZhipuaiChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system" ] }, "content": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } }, "required": [ "type", "image_url" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } } ] }, "name": { "type": "string" } }, "required": [ "role", "content" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "nullable": true, "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "required": [ "id", "type", "function" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "function_call": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] } }, "required": [ "role" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "content": { "type": "string" }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "function" ] }, "content": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://docs.z.ai/api-reference/llm/chat-completion#body\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } }, "required": [ "type", "function" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } ], "description": "\n A function tool that can be used to generate a response.\n\n https://docs.z.ai/api-reference/llm/chat-completion#body\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://docs.z.ai/api-reference/llm/chat-completion#body\n " } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, "request_id": { "type": "string" }, "do_sample": { "type": "boolean" }, "stream": { "type": "boolean" }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] }, "clear_thinking": { "type": "boolean" } }, "required": [ "type" ] }, "temperature": { "nullable": true, "type": "number" }, "top_p": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "tool_stream": { "type": "boolean" }, "stop": { "type": "array", "items": { "type": "string" } }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object" ] } }, "required": [ "type" ] }, "user_id": { "type": "string" } }, "required": [ "model", "messages" ] }, "ZhipuaiChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "request_id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "sensitive", "network_error" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "reasoning_content": { "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "required": [ "id", "type", "function" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] } }, "required": [ "role" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "required": [ "finish_reason", "message" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "prompt_tokens_details": { "description": "https://docs.z.ai/api-reference/llm/chat-completion#response", "type": "object", "properties": { "cached_tokens": { "type": "number" } }, "required": [ "cached_tokens" ] } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" }, "web_search": { "description": "https://docs.z.ai/api-reference/llm/chat-completion#response", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "link": { "type": "string" }, "media": { "type": "string" }, "icon": { "type": "string" }, "refer": { "type": "string" }, "publish_date": { "type": "string" } }, "required": [ "title", "content", "link", "media", "icon", "refer", "publish_date" ] } } }, "required": [ "id", "choices", "created", "model", "object" ] }, "DeepSeekChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, "DeepSeekChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "ArchestraChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, "ArchestraChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "MinimaxChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } } }, "required": [ "role" ] }, { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } ] } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "stream": { "type": "boolean" }, "temperature": { "nullable": true, "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "nullable": true, "type": "number", "minimum": 0, "maximum": 1 }, "max_tokens": { "nullable": true, "type": "number" }, "n": { "type": "number", "enum": [ 1 ] }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object" ] } }, "required": [ "type" ] }, "user": { "type": "string" }, "reasoning_split": { "type": "boolean" }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "type" ] }, "extra_body": { "type": "object", "properties": { "reasoning_split": { "type": "boolean" } } } }, "required": [ "model", "messages" ] }, "MinimaxChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://platform.minimax.io/docs/api-reference/text-openai-api#response" } }, "required": [ "finish_reason", "message" ], "description": "https://platform.minimax.io/docs/api-reference/text-openai-api#response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "number" } } } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://platform.minimax.io/docs/api-reference/text-openai-api#usage" } }, "required": [ "id", "choices", "created", "model", "object" ] }, "XaiChatCompletionRequestInput": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ] }, "XaiChatCompletionResponseInput": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "UserConfigFieldDefaultInput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] }, "UserConfigFieldInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "directory", "file" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "default": { "allOf": [ { "$ref": "#/components/schemas/UserConfigFieldDefaultInput" } ] }, "multiple": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "min": { "type": "number" }, "max": { "type": "number" }, "headerName": { "type": "string" }, "valuePrefix": { "type": "string" } }, "required": [ "type", "title", "description" ] }, "InteractionVirtualKeyInput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "keyType": { "type": "string", "enum": [ "standard", "passthrough" ] }, "tokenStart": { "type": "string" }, "ownerUserId": { "nullable": true, "type": "string" }, "ownerUserName": { "nullable": true, "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "createdByUserName": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "scope", "keyType", "tokenStart", "ownerUserId", "ownerUserName", "teams", "createdByUserName" ] }, "LogContentNotStored": { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "log_content_policy" ] }, "isError": { "type": "boolean" }, "errorType": { "type": "string", "enum": [ "auth_required", "auth_expired", "assigned_credential_unavailable", "tool_state", "cancelled", "generic" ] }, "archestraExecutedAs": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] }, "ownerUserId": { "nullable": true, "type": "string" }, "ownerName": { "nullable": true, "type": "string" } }, "required": [ "kind", "ownerUserId", "ownerName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "team" ] }, "teamId": { "type": "string" }, "teamName": { "nullable": true, "type": "string" } }, "required": [ "kind", "teamId", "teamName" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "org" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idp_exchange" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idp_passthrough" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller_headers" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "platform" ] }, "callerUserId": { "nullable": true, "type": "string" } }, "required": [ "kind", "callerUserId" ], "additionalProperties": false } ] } }, "required": [ "__redacted" ], "additionalProperties": false }, "TextSearchLanguage": { "type": "string", "enum": [ "simple", "arabic", "armenian", "basque", "catalan", "danish", "dutch", "english", "finnish", "french", "german", "greek", "hindi", "hungarian", "indonesian", "irish", "italian", "lithuanian", "nepali", "norwegian", "portuguese", "romanian", "russian", "serbian", "spanish", "swedish", "tamil", "turkish", "yiddish" ] }, "ContextualRetrievalMode": { "type": "string", "enum": [ "disabled", "document", "chunk" ] }, "EmbeddingDimensions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "enum": [ 3072, 1536, 1408, 1024, 768, 384 ] }, "LocalConfigEnvironmentDefault": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "OpenAiChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "OpenAiChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": false }, "GeminiGenerateContentRequest": { "type": "object", "properties": { "contents": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the author of this content." }, "parts": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "text": { "type": "string" }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "inlineData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "inlineData" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionCall": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionCall" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "response": { "type": "object", "additionalProperties": {} }, "willContinue": { "type": "boolean" }, "scheduling": { "type": "string", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] } }, "required": [ "name", "response" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionResponse" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "fileData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "fileUri": { "type": "string" } }, "required": [ "fileUri" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "fileData" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "language": { "type": "string", "enum": [ "LANGUAGE_UNSPECIFIED", "PYTHON" ] }, "executableCode": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "language", "executableCode" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "codeExecutionResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "OUTCOME_UNSPECIFIED", "OUTCOME_OK", "OUTCOME_FAILED", "OUTCOME_DEADLINE_EXCEEDED" ], "description": "Outcome of the code execution." }, "output": { "type": "string" } }, "required": [ "outcome" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "codeExecutionResult" ], "additionalProperties": false } ] } ], "description": "https://ai.google.dev/api/caching#Part" } } }, "required": [ "role", "parts" ], "additionalProperties": false, "description": "\nThe base structured datatype containing multi-part content of a message.\n\nA Content includes a role field designating the producer of the Content and a parts field containing multi-part data that contains the content of the message turn.\n\nhttps://ai.google.dev/api/caching#Content\n" }, "description": "The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like chat, this is a repeated field that contains the conversation history and the latest request" }, "tools": { "description": "A list of Tools the Model may use to generate the next response. A Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the Model. Supported Tools are Function and codeExecution. Refer to the Function calling and the Code execution guides to learn more.", "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "additionalProperties": false, "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "additionalProperties": false, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } }, { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "additionalProperties": false, "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "additionalProperties": false, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } ] }, "toolConfig": { "description": "Tool configuration for any Tool specified in the request.", "type": "object", "properties": { "functionCallingConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "ANY", "NONE" ] }, "allowedFunctionNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "functionCallingConfig" ], "additionalProperties": false }, "safetySettings": { "description": "A list of unique SafetySetting instances for blocking unsafe content.", "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "HARM_CATEGORY_UNSPECIFIED", "HARM_CATEGORY_DEROGATORY", "HARM_CATEGORY_TOXICITY", "HARM_CATEGORY_VIOLENCE", "HARM_CATEGORY_SEXUAL", "HARM_CATEGORY_MEDICAL", "HARM_CATEGORY_DANGEROUS", "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY" ], "description": "\n The category for this setting\n\n https://ai.google.dev/api/generate-content#v1beta.HarmCategory\n" }, "threshold": { "type": "string", "enum": [ "HARM_BLOCK_THRESHOLD_UNSPECIFIED", "BLOCK_LOW_AND_ABOVE", "BLOCK_MEDIUM_AND_ABOVE", "BLOCK_ONLY_HIGH", "BLOCK_NONE", "OFF" ], "description": "\n Controls the probability threshold at which harm is blocked.\n\n https://ai.google.dev/api/generate-content#HarmBlockThreshold\n " } }, "required": [ "category", "threshold" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.SafetySetting" } }, "systemInstruction": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } } }, "required": [ "parts" ], "additionalProperties": false, "description": "Developer set system instruction(s). Currently, text only." }, "generationConfig": { "type": "object", "properties": { "stopSequences": { "type": "array", "items": { "type": "string" } }, "responseMimeType": { "type": "string" }, "responseSchema": {}, "_responseJsonSchema": {}, "responseJsonSchema": {}, "responseModalities": { "type": "array", "items": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" } }, "candidateCount": { "type": "number" }, "maxOutputTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "topK": { "type": "number" }, "seed": { "type": "number" }, "presencePenalty": { "type": "number" }, "frequencyPenalty": { "type": "number" }, "responseLogprobs": { "type": "boolean" }, "logProbs": { "type": "number" }, "enableEnhancedCivicAnswers": { "type": "boolean" }, "speechConfig": {}, "thinkingConfig": {}, "imageConfig": {}, "mediaResolution": { "description": "https://ai.google.dev/api/generate-content#MediaResolution", "type": "string", "enum": [ "MEDIA_RESOLUTION_UNSPECIFIED", "MEDIA_RESOLUTION_LOW", "MEDIA_RESOLUTION_MEDIUM", "MEDIA_RESOLUTION_HIGH" ] } }, "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.GenerationConfig" }, "cachedContent": { "description": "The name of the content cached to use as context to serve the prediction. Format: cachedContents/{cachedContent}", "type": "string" }, "config": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "additionalProperties": false, "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "additionalProperties": false, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } }, { "type": "object", "properties": { "functionDeclarations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function. Must start with a letter or underscore and contain only a-z, A-Z, 0-9, underscores, dots, colons, or dashes, with a maximum length of 128." }, "description": { "type": "string", "description": "A brief description of the function." }, "behavior": { "description": "https://ai.google.dev/api/caching#Behavior", "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ] }, "parameters": { "description": "Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.", "type": "object", "additionalProperties": {} }, "parametersJsonSchema": {}, "response": {}, "responseJsonSchema": {} }, "required": [ "name", "description" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#FunctionDeclaration" } }, "googleSearchRetrieval": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ], "description": "https://ai.google.dev/api/caching#Mode" }, "dynamicThreshold": { "type": "number" } }, "required": [ "mode", "dynamicThreshold" ], "additionalProperties": false, "description": "\n Specifies the dynamic retrieval configuration for the given source.\n\n https://ai.google.dev/api/caching#DynamicRetrievalConfig\n " } }, "required": [ "dynamicRetrievalConfig" ], "additionalProperties": false, "description": "https://ai.google.dev/api/caching#GoogleSearchRetrieval" }, "codeExecution": {}, "googleSearch": {}, "urlContext": {}, "googleMaps": {}, "enterpriseWebSearch": {}, "fileSearch": {} }, "additionalProperties": false, "description": "\nTool details that the model may use to generate response.\n\nA Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model.\n\nhttps://ai.google.dev/api/caching#Tool\n" } ] }, "toolConfig": { "description": "Tool configuration for any Tool specified in the request.", "type": "object", "properties": { "functionCallingConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "ANY", "NONE" ] }, "allowedFunctionNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "functionCallingConfig" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "contents" ], "additionalProperties": false }, "GeminiGenerateContentResponse": { "type": "object", "properties": { "candidates": { "description": "Candidate responses from the model", "type": "array", "items": { "type": "object", "properties": { "content": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the author of this content." }, "parts": { "type": "array", "items": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "text": { "type": "string" }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "inlineData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "inlineData" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionCall": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionCall" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "functionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "response": { "type": "object", "additionalProperties": {} }, "willContinue": { "type": "boolean" }, "scheduling": { "type": "string", "enum": [ "SCHEDULING_UNSPECIFIED", "SILENT", "WHEN_IDLE", "INTERRUPT" ] } }, "required": [ "name", "response" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "functionResponse" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "fileData": { "type": "object", "properties": { "mimeType": { "type": "string" }, "fileUri": { "type": "string" } }, "required": [ "fileUri" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "fileData" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "language": { "type": "string", "enum": [ "LANGUAGE_UNSPECIFIED", "PYTHON" ] }, "executableCode": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "language", "executableCode" ], "additionalProperties": false }, { "type": "object", "properties": { "thought": { "description": "Indicates if the part is thought from the model", "type": "boolean" }, "thoughtSignature": { "description": "An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string", "type": "string" }, "codeExecutionResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "OUTCOME_UNSPECIFIED", "OUTCOME_OK", "OUTCOME_FAILED", "OUTCOME_DEADLINE_EXCEEDED" ], "description": "Outcome of the code execution." }, "output": { "type": "string" } }, "required": [ "outcome" ], "additionalProperties": false }, "metadata": { "description": "https://ai.google.dev/api/caching#PartMetadata", "anyOf": [ { "type": "object", "properties": { "startOffset": { "description": "The start offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "endOffset": { "description": "The end offset of the video. A duration in seconds with up to nine fractional digits, ending with 's'. Example: '3.5s'", "type": "string" }, "fps": { "description": "The frame rate of the video sent to the model. If not specified, the default value will be 1.0. The fps range is (0.0, 24.0]", "type": "number" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/caching#VideoMetadata" } ] } }, "required": [ "codeExecutionResult" ], "additionalProperties": false } ] } ], "description": "https://ai.google.dev/api/caching#Part" } } }, "required": [ "role", "parts" ], "additionalProperties": false, "description": "\nThe base structured datatype containing multi-part content of a message.\n\nA Content includes a role field designating the producer of the Content and a parts field containing multi-part data that contains the content of the message turn.\n\nhttps://ai.google.dev/api/caching#Content\n" }, "finishReason": { "description": "\n The reason why the model stopped generating tokens.\n\n If empty, the model has not stopped generating tokens.\n\n https://ai.google.dev/api/generate-content#FinishReason\n", "anyOf": [ { "type": "string", "enum": [ "FINISH_REASON_UNSPECIFIED", "STOP", "MAX_TOKENS", "SAFETY", "RECITATION", "LANGUAGE", "OTHER", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII", "MALFORMED_FUNCTION_CALL", "IMAGE_SAFETY", "IMAGE_PROHIBITED_CONTENT", "IMAGE_OTHER", "NO_IMAGE", "IMAGE_RECITATION", "UNEXPECTED_TOOL_CALL", "TOO_MANY_TOOL_CALLS" ] }, { "type": "string" } ] }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "HARM_CATEGORY_UNSPECIFIED", "HARM_CATEGORY_DEROGATORY", "HARM_CATEGORY_TOXICITY", "HARM_CATEGORY_VIOLENCE", "HARM_CATEGORY_SEXUAL", "HARM_CATEGORY_MEDICAL", "HARM_CATEGORY_DANGEROUS", "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY" ], "description": "\n The category for this setting\n\n https://ai.google.dev/api/generate-content#v1beta.HarmCategory\n" }, "probability": { "type": "string", "enum": [ "HARM_PROBABILITY_UNSPECIFIED", "NEGLIGIBLE", "LOW", "MEDIUM", "HIGH" ], "description": "https://ai.google.dev/api/generate-content#HarmProbability" }, "blocked": { "description": "Was this content blocked because of this rating?", "type": "boolean" } }, "required": [ "category", "probability" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.SafetyRating" } }, "citationMetadata": { "description": "https://ai.google.dev/api/generate-content#citationmetadata", "type": "object", "properties": { "citationSources": { "type": "array", "items": { "description": "https://ai.google.dev/api/generate-content#CitationSource", "type": "object", "properties": { "startIndex": { "type": "number" }, "endIndex": { "type": "number" }, "uri": { "type": "string" }, "license": { "type": "string" } }, "additionalProperties": false } } }, "required": [ "citationSources" ], "additionalProperties": false }, "tokenCount": { "type": "number" }, "groundingAttributions": { "type": "array", "items": {} }, "groundingMetadata": {}, "avgLogprobs": { "type": "number" }, "logprobsResult": {}, "urlContextMetadata": {}, "index": { "description": "Index of the candidate in the list of response candidates.", "type": "number" }, "finishMessage": { "description": "Details the reason why the model stopped generating tokens. This is populated only when finishReason is set.", "type": "string" } }, "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#candidate" } }, "promptFeedback": { "description": "Returns the prompt's feedback related to the content filters", "type": "object", "properties": { "blockReason": { "description": "Specifies the reason why the prompt was blocked. https://ai.google.dev/api/generate-content#BlockReason", "anyOf": [ { "type": "string", "enum": [ "BLOCK_REASON_UNSPECIFIED", "SAFETY", "OTHER", "BLOCKLIST", "PROHIBITED_CONTENT", "IMAGE_SAFETY" ] }, { "type": "string" } ] }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "HARM_CATEGORY_UNSPECIFIED", "HARM_CATEGORY_DEROGATORY", "HARM_CATEGORY_TOXICITY", "HARM_CATEGORY_VIOLENCE", "HARM_CATEGORY_SEXUAL", "HARM_CATEGORY_MEDICAL", "HARM_CATEGORY_DANGEROUS", "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY" ], "description": "\n The category for this setting\n\n https://ai.google.dev/api/generate-content#v1beta.HarmCategory\n" }, "probability": { "type": "string", "enum": [ "HARM_PROBABILITY_UNSPECIFIED", "NEGLIGIBLE", "LOW", "MEDIUM", "HIGH" ], "description": "https://ai.google.dev/api/generate-content#HarmProbability" }, "blocked": { "description": "Was this content blocked because of this rating?", "type": "boolean" } }, "required": [ "category", "probability" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.SafetyRating" } } }, "additionalProperties": false }, "usageMetadata": { "description": "Metadata on the generation requests' token usage", "type": "object", "properties": { "trafficType": { "description": "Traffic tier that served the request.", "type": "string" }, "promptTokenCount": { "type": "number" }, "cachedContentTokenCount": { "type": "number" }, "candidatesTokenCount": { "type": "number" }, "toolUsePromptTokenCount": { "type": "number" }, "thoughtsTokenCount": { "type": "number" }, "totalTokenCount": { "type": "number" }, "promptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } }, "cacheTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } }, "candidatesTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } }, "toolUsePromptTokensDetails": { "type": "array", "items": { "type": "object", "properties": { "modality": { "type": "string", "enum": [ "MODALITY_UNSPECIFIED", "TEXT", "IMAGE", "AUDIO" ], "description": "https://ai.google.dev/api/generate-content#Modality" }, "tokenCount": { "type": "number", "description": "Number of tokens" } }, "required": [ "modality", "tokenCount" ], "additionalProperties": false, "description": "https://ai.google.dev/api/generate-content#v1beta.ModalityTokenCount" } } }, "additionalProperties": false }, "modelVersion": { "description": "The model version used to generate the response.", "type": "string" }, "responseId": { "description": "The unique response ID.", "type": "string" } }, "additionalProperties": false }, "AnthropicMessagesRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ], "additionalProperties": false } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" } }, "required": [ "model", "messages", "max_tokens" ], "additionalProperties": {} }, "AnthropicMessagesResponse": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "citations": { "nullable": true, "type": "array", "items": {} }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "citations", "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": {} } ] } }, "model": { "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "stop_reason": { "nullable": true }, "stop_sequence": { "nullable": true, "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "cache_read_input_tokens": { "nullable": true, "type": "number" }, "cache_creation_input_tokens": { "nullable": true, "type": "number" }, "cache_creation": { "nullable": true, "type": "object", "properties": { "ephemeral_1h_input_tokens": { "nullable": true, "type": "number" }, "ephemeral_5m_input_tokens": { "nullable": true, "type": "number" } }, "additionalProperties": false } }, "required": [ "input_tokens", "output_tokens" ], "additionalProperties": {} } }, "required": [ "id", "content", "model", "role", "type", "usage" ], "additionalProperties": {} }, "CerebrasChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "CerebrasChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/Cerebras/cerebras-cloud-sdk-node/blob/main/src/resources/chat/completions.ts" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/Cerebras/cerebras-cloud-sdk-node/blob/main/src/resources/chat/completions.ts" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": false }, "CohereChatRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false } }, "required": [ "type", "image_url" ], "additionalProperties": false } ] } } ] } }, "required": [ "role", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_result" ] }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "type", "tool_call_id", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" } }, "required": [ "type", "thinking" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "id", "type", "function" ], "additionalProperties": false } } }, "required": [ "role" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system" ] }, "content": { "type": "string" } }, "required": [ "role", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "role", "tool_call_id", "content" ], "additionalProperties": false } ] } }, "stream": { "type": "boolean" }, "temperature": { "type": "number" }, "max_tokens": { "type": "number" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false } }, "tool_choice": { "type": "string", "enum": [ "REQUIRED", "NONE" ] }, "safety_mode": { "type": "string", "enum": [ "CONTEXTUAL", "STRICT", "OFF" ] }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object", "text" ] }, "json_schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": false }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "k": { "type": "number" }, "p": { "type": "number" }, "seed": { "type": "number" }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "logprobs": { "type": "boolean" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "CohereChatResponse": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_result" ] }, "tool_call_id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "type", "tool_call_id", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" } }, "required": [ "type", "thinking" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "id", "type", "function" ], "additionalProperties": false } } }, "required": [ "role" ], "additionalProperties": false }, "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "COMPLETE", "MAX_TOKENS", "STOP_SEQUENCE", "TOOL_CALL", "ERROR" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "billed_units": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" } }, "additionalProperties": false }, "tokens": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "id", "message", "finish_reason" ], "additionalProperties": false }, "MistralChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "MistralChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "PerplexityChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" }, "stream_mode": { "type": "string", "enum": [ "full", "concise" ] } }, "required": [ "model", "messages" ], "additionalProperties": false }, "PerplexityChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "GroqChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "GroqChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "OpenrouterChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ] } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ] } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object", "json_schema" ] } }, "required": [ "type" ], "additionalProperties": {} }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" }, "reasoning": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "effort": { "type": "string" }, "max_tokens": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "exclude": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "model", "messages" ], "additionalProperties": false }, "OpenrouterChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "JevDecisionsRequest": { "type": "object", "properties": { "model": { "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ], "description": "The content the questions are about" }, "questions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "description": "Question kind: noul, choice, or score" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "criteria": {} }, "required": [ "type", "instructions", "criteria" ], "additionalProperties": {} }, "description": "Decision questions keyed by name" } }, "required": [ "model", "state", "questions" ], "additionalProperties": {} }, "JevDecisionsResponse": { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "answers": { "type": "object", "additionalProperties": {} }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cost": { "type": "number", "minimum": 0 } }, "additionalProperties": {} } }, "required": [ "answers" ], "additionalProperties": {} }, "VllmChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "A developer message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "A system message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "Image URL details" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "An image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_audio" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "Audio input details" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "An audio content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "File details" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "A file content part" } ], "description": "A content part in a message" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "A user message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "A refusal content part" } } ] }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "Function call details" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } }, "reasoning": { "nullable": true, "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" } }, "required": [ "role" ], "additionalProperties": false, "description": "An assistant message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "Image URL details" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "An image content part" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "A tool result message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "A function result message (deprecated)" } ], "description": "A message in the conversation" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "A function tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ], "additionalProperties": false } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "A custom tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "A custom tool in the flat Responses-API shape (see the OpenAI provider's ResponsesStyleCustomToolSchema)" } ], "description": "A tool definition" } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model.\n auto: allows the model to pick from allowed tools or generate a message.\n required: requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "A function tool definition" } } } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "Allowed tools configuration" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "Allowed tool choice configuration" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "Named function tool choice" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ], "additionalProperties": false } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "A custom tool definition" } ], "description": "Tool choice option" }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "stream": { "nullable": true, "type": "boolean" }, "top_p": { "nullable": true, "type": "number" }, "top_k": { "nullable": true, "type": "number" }, "frequency_penalty": { "nullable": true, "type": "number" }, "presence_penalty": { "nullable": true, "type": "number" }, "repetition_penalty": { "nullable": true, "type": "number" }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "nullable": true, "type": "number" }, "n": { "nullable": true, "type": "number" }, "best_of": { "nullable": true, "type": "number" }, "logprobs": { "nullable": true, "type": "boolean" }, "top_logprobs": { "nullable": true, "type": "number" }, "chat_template_kwargs": { "type": "object", "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "VllmChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "Function call details" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } }, "reasoning": { "nullable": true, "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" } }, "required": [ "role" ], "additionalProperties": false, "description": "The assistant message in the response" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "A choice in the chat completion response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": {}, "prompt_tokens_details": {} }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "Token usage statistics for the completion" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": false }, "OllamaChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "A developer message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "A system message" }, { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "Image URL details" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "An image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "input_audio" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "Audio input details" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "An audio content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "File details" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "A file content part" } ], "description": "A content part in a message" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "A user message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" } }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "A refusal content part" } } ] }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "Function call details" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } } }, "required": [ "role" ], "additionalProperties": false, "description": "An assistant message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "Image URL details" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "An image content part" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "A tool result message" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "A function result message (deprecated)" } ], "description": "A message in the conversation" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "A function tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ], "additionalProperties": false } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "A custom tool definition" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "A custom tool in the flat Responses-API shape (see the OpenAI provider's ResponsesStyleCustomToolSchema)" } ], "description": "A tool definition" } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model.\n auto: allows the model to pick from allowed tools or generate a message.\n required: requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n The parameters the functions accepts, described as a JSON Schema object.\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "A function definition for tool calling" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "A function tool definition" } } } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "Allowed tools configuration" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "Allowed tool choice configuration" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "Named function tool choice" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool" }, "description": { "description": "Description of the tool", "type": "string" }, "format": { "description": "The input format for the custom tool", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar" } }, "required": [ "definition", "syntax" ], "additionalProperties": false } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "A custom tool definition" } ], "description": "Tool choice option" }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "stream": { "nullable": true, "type": "boolean" }, "top_p": { "nullable": true, "type": "number" }, "frequency_penalty": { "nullable": true, "type": "number" }, "presence_penalty": { "nullable": true, "type": "number" }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "seed": { "nullable": true, "type": "number" }, "n": { "nullable": true, "type": "number" }, "reasoning_effort": { "nullable": true, "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "OllamaChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "Function call details" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "A function tool call in the message" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "Custom tool call details" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "A custom tool call in the message" } ], "description": "A tool call in the assistant message" } } }, "required": [ "role" ], "additionalProperties": false, "description": "The assistant message in the response" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "A choice in the chat completion response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": {}, "prompt_tokens_details": {} }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "Token usage statistics for the completion" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": false }, "OllamaNativeChatRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ] }, "thinking": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "tool_calls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "function": { "type": "object", "properties": { "index": { "type": "number" }, "name": { "type": "string" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "name", "arguments" ], "additionalProperties": {} } }, "required": [ "function" ], "additionalProperties": {} } }, "tool_name": { "type": "string" }, "tool_call_id": { "type": "string" } }, "required": [ "role" ], "additionalProperties": {} } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": {} } }, "required": [ "type", "function" ], "additionalProperties": {} } }, "format": {}, "options": { "type": "object", "properties": { "temperature": { "type": "number" }, "top_k": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "top_p": { "type": "number" }, "min_p": { "type": "number" }, "typical_p": { "type": "number" }, "seed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "repeat_penalty": { "type": "number" }, "repeat_last_n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "presence_penalty": { "type": "number" }, "frequency_penalty": { "type": "number" }, "stop": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 256 } }, "num_keep": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "num_ctx": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "num_predict": { "type": "integer", "minimum": -2, "maximum": 9007199254740991 } }, "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "keep_alive": {}, "think": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "temperature": { "nullable": true, "type": "number" }, "top_p": { "nullable": true, "type": "number" }, "max_output_tokens": { "nullable": true, "type": "number" }, "truncate": { "type": "boolean" }, "shift": { "type": "boolean" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, "OllamaNativeChatResponse": { "type": "object", "properties": { "model": { "type": "string" }, "created_at": { "type": "string" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "thinking": { "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "function": { "type": "object", "properties": { "index": { "type": "number" }, "name": { "type": "string" }, "arguments": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": {} } ] } }, "required": [ "name", "arguments" ], "additionalProperties": {} } }, "required": [ "function" ], "additionalProperties": {} } } }, "required": [ "role" ], "additionalProperties": {} }, "done": { "type": "boolean" }, "done_reason": { "type": "string" }, "total_duration": { "type": "number" }, "load_duration": { "type": "number" }, "prompt_eval_count": { "type": "number" }, "prompt_eval_duration": { "type": "number" }, "eval_count": { "type": "number" }, "eval_duration": { "type": "number" } }, "required": [ "model", "message", "done" ], "additionalProperties": {} }, "ZhipuaiChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system" ] }, "content": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image_url" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } } ] }, "name": { "type": "string" } }, "required": [ "role", "content" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "nullable": true, "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "function_call": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false } }, "required": [ "role" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tool" ] }, "content": { "type": "string" }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "function" ] }, "content": { "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://docs.z.ai/api-reference/llm/chat-completion#body\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" } ], "description": "\n A function tool that can be used to generate a response.\n\n https://docs.z.ai/api-reference/llm/chat-completion#body\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://docs.z.ai/api-reference/llm/chat-completion#body\n " } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#body" }, "request_id": { "type": "string" }, "do_sample": { "type": "boolean" }, "stream": { "type": "boolean" }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] }, "clear_thinking": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "temperature": { "nullable": true, "type": "number" }, "top_p": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "tool_stream": { "type": "boolean" }, "stop": { "type": "array", "items": { "type": "string" } }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, "user_id": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "ZhipuaiChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "request_id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "sensitive", "network_error" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "reasoning_content": { "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } ], "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "function_call": { "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false } }, "required": [ "role" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "prompt_tokens_details": { "description": "https://docs.z.ai/api-reference/llm/chat-completion#response", "type": "object", "properties": { "cached_tokens": { "type": "number" } }, "required": [ "cached_tokens" ], "additionalProperties": false } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://docs.z.ai/api-reference/llm/chat-completion#response" }, "web_search": { "description": "https://docs.z.ai/api-reference/llm/chat-completion#response", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "link": { "type": "string" }, "media": { "type": "string" }, "icon": { "type": "string" }, "refer": { "type": "string" }, "publish_date": { "type": "string" } }, "required": [ "title", "content", "link", "media", "icon", "refer", "publish_date" ], "additionalProperties": false } } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": false }, "DeepSeekChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, "DeepSeekChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "ArchestraChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, "ArchestraChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "MinimaxChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } } }, "required": [ "role" ], "additionalProperties": false }, { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } ] } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "stream": { "type": "boolean" }, "temperature": { "nullable": true, "type": "number", "minimum": 0, "maximum": 1 }, "top_p": { "nullable": true, "type": "number", "minimum": 0, "maximum": 1 }, "max_tokens": { "nullable": true, "type": "number" }, "n": { "type": "number", "enum": [ 1 ] }, "stop": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, "user": { "type": "string" }, "reasoning_split": { "type": "boolean" }, "thinking": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "type" ], "additionalProperties": false }, "extra_body": { "type": "object", "properties": { "reasoning_split": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "model", "messages" ], "additionalProperties": false }, "MinimaxChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "reasoning_details": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://platform.minimax.io/docs/api-reference/text-openai-api#response" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://platform.minimax.io/docs/api-reference/text-openai-api#response" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "type": "object", "properties": { "reasoning_tokens": { "type": "number" } }, "additionalProperties": false } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://platform.minimax.io/docs/api-reference/text-openai-api#usage" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": false }, "XaiChatCompletionRequest": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": false }, "XaiChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, "UserConfigFieldDefault": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] }, "UserConfigField": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "directory", "file" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "default": { "allOf": [ { "$ref": "#/components/schemas/UserConfigFieldDefault" } ] }, "multiple": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "min": { "type": "number" }, "max": { "type": "number" }, "headerName": { "type": "string" }, "valuePrefix": { "type": "string" } }, "required": [ "type", "title", "description" ], "additionalProperties": false }, "InteractionVirtualKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "keyType": { "type": "string", "enum": [ "standard", "passthrough" ] }, "tokenStart": { "type": "string" }, "ownerUserId": { "nullable": true, "type": "string" }, "ownerUserName": { "nullable": true, "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "createdByUserName": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "scope", "keyType", "tokenStart", "ownerUserId", "ownerUserName", "teams", "createdByUserName" ], "additionalProperties": false } } }, "paths": { "/api/a2a/remote-agents/{id}/transfer-ownership": { "post": { "operationId": "transferRemoteAgentOwnership", "tags": [ "Ownership" ], "description": "Transfer ownership to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } } }, "/api/agents/{agentId}/a2a-delegations": { "get": { "operationId": "getAgentA2aDelegations", "tags": [ "Agent Delegations" ], "description": "List external A2A agents explicitly assigned as subagents.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "remoteAgentId", "connectionId", "toolId", "name", "description", "enabled" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "syncAgentA2aDelegations", "tags": [ "Agent Delegations" ], "description": "Replace an agent's explicit external A2A subagent assignments.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "connectionIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "removed": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "added", "removed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/a2a/remote-agents/inspect": { "post": { "operationId": "inspectA2aRemoteAgent", "tags": [ "Outbound A2A Agents" ], "description": "Resolve and validate an outbound A2A Agent Card without saving it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:create`](/docs/reference/permissions#agent:create): Create new agents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "well_known" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inline_card" ] }, "agentCard": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "agentCard" ] } ] }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "credential": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key" ] }, "headerName": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" }, "credential": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "type", "headerName" ] } ] }, "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "agentCard": { "type": "object", "additionalProperties": {} }, "cardHash": { "type": "string" }, "selectedInterface": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "supportedAuthTypes": { "type": "array", "items": { "type": "string", "enum": [ "none", "bearer", "api_key" ] } }, "selectedSecurityRequirement": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "name", "description", "agentCard", "cardHash", "selectedInterface", "supportedAuthTypes", "selectedSecurityRequirement" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:create" ] } } }, "/api/a2a/remote-agents": { "get": { "operationId": "listA2aRemoteAgents", "tags": [ "Outbound A2A Agents" ], "description": "List configured outbound A2A agents.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "teamId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "authorId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "discoveryMode": { "type": "string", "enum": [ "well_known", "card_url", "inline_card" ] }, "discoveryUrl": { "nullable": true, "type": "string" }, "agentCard": { "type": "object", "additionalProperties": {} }, "cardHash": { "type": "string" }, "lastDiscoveredAt": { "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "selectedInterface": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "securityRequirement": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key" ] }, "authConfig": { "type": "object", "properties": { "headerName": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "lastVerifiedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredential": { "type": "boolean" } }, "required": [ "id", "remoteAgentId", "selectedInterface", "securityRequirement", "authType", "authConfig", "enabled", "lastVerifiedAt", "createdAt", "updatedAt", "hasCredential" ], "additionalProperties": false }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignmentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "authorId", "name", "description", "discoveryMode", "discoveryUrl", "agentCard", "cardHash", "lastDiscoveredAt", "createdByServiceAccountId", "createdAt", "updatedAt", "connection", "toolId", "assignmentCount", "lastUsedAt", "authorName", "createdBy" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } }, "post": { "operationId": "createA2aRemoteAgent", "tags": [ "Outbound A2A Agents" ], "description": "Configure an outbound A2A agent and its default connection.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:create`](/docs/reference/permissions#agent:create): Create new agents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "well_known" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inline_card" ] }, "agentCard": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "agentCard" ] } ] }, "auth": { "default": { "type": "none" }, "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "credential": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "type", "credential" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key" ] }, "headerName": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" }, "credential": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "type", "headerName", "credential" ] } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "nullable": true, "type": "string", "maxLength": 2000 }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "discoveryMode": { "type": "string", "enum": [ "well_known", "card_url", "inline_card" ] }, "discoveryUrl": { "nullable": true, "type": "string" }, "agentCard": { "type": "object", "additionalProperties": {} }, "cardHash": { "type": "string" }, "lastDiscoveredAt": { "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "selectedInterface": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "securityRequirement": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key" ] }, "authConfig": { "type": "object", "properties": { "headerName": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "lastVerifiedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredential": { "type": "boolean" } }, "required": [ "id", "remoteAgentId", "selectedInterface", "securityRequirement", "authType", "authConfig", "enabled", "lastVerifiedAt", "createdAt", "updatedAt", "hasCredential" ], "additionalProperties": false }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignmentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "authorId", "name", "description", "discoveryMode", "discoveryUrl", "agentCard", "cardHash", "lastDiscoveredAt", "createdByServiceAccountId", "createdAt", "updatedAt", "connection", "toolId", "assignmentCount", "lastUsedAt", "authorName", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:create" ] } } }, "/api/a2a/remote-agents/{id}": { "get": { "operationId": "getA2aRemoteAgent", "tags": [ "Outbound A2A Agents" ], "description": "Get one configured outbound A2A agent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "discoveryMode": { "type": "string", "enum": [ "well_known", "card_url", "inline_card" ] }, "discoveryUrl": { "nullable": true, "type": "string" }, "agentCard": { "type": "object", "additionalProperties": {} }, "cardHash": { "type": "string" }, "lastDiscoveredAt": { "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "selectedInterface": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "securityRequirement": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key" ] }, "authConfig": { "type": "object", "properties": { "headerName": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "lastVerifiedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredential": { "type": "boolean" } }, "required": [ "id", "remoteAgentId", "selectedInterface", "securityRequirement", "authType", "authConfig", "enabled", "lastVerifiedAt", "createdAt", "updatedAt", "hasCredential" ], "additionalProperties": false }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignmentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "authorId", "name", "description", "discoveryMode", "discoveryUrl", "agentCard", "cardHash", "lastDiscoveredAt", "createdByServiceAccountId", "createdAt", "updatedAt", "connection", "toolId", "assignmentCount", "lastUsedAt", "authorName", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } }, "put": { "operationId": "updateA2aRemoteAgent", "tags": [ "Outbound A2A Agents" ], "description": "Update an outbound A2A agent, refresh its card, or rotate its credential.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "nullable": true, "type": "string", "maxLength": 2000 }, "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "well_known" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card_url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "inline_card" ] }, "agentCard": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "agentCard" ] } ] }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "credential": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "type", "credential" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_key" ] }, "headerName": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" }, "credential": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "type", "headerName", "credential" ] } ] }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "discoveryMode": { "type": "string", "enum": [ "well_known", "card_url", "inline_card" ] }, "discoveryUrl": { "nullable": true, "type": "string" }, "agentCard": { "type": "object", "additionalProperties": {} }, "cardHash": { "type": "string" }, "lastDiscoveredAt": { "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "selectedInterface": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "securityRequirement": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key" ] }, "authConfig": { "type": "object", "properties": { "headerName": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "lastVerifiedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredential": { "type": "boolean" } }, "required": [ "id", "remoteAgentId", "selectedInterface", "securityRequirement", "authType", "authConfig", "enabled", "lastVerifiedAt", "createdAt", "updatedAt", "hasCredential" ], "additionalProperties": false }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignmentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "authorId", "name", "description", "discoveryMode", "discoveryUrl", "agentCard", "cardHash", "lastDiscoveredAt", "createdByServiceAccountId", "createdAt", "updatedAt", "connection", "toolId", "assignmentCount", "lastUsedAt", "authorName", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } }, "delete": { "operationId": "deleteA2aRemoteAgent", "tags": [ "Outbound A2A Agents" ], "description": "Delete an outbound A2A agent and remove its subagent assignments.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } } }, "/api/a2a/remote-agents/{id}/runs": { "get": { "operationId": "listA2aRemoteAgentRuns", "tags": [ "Outbound A2A Agents" ], "description": "List recent outbound A2A protocol outcomes for one configured external agent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "parentAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "nullable": true, "type": "string" }, "conversationId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolCallId": { "nullable": true, "type": "string" }, "messageId": { "type": "string" }, "remoteTaskId": { "nullable": true, "type": "string" }, "remoteContextId": { "nullable": true, "type": "string" }, "state": { "type": "string", "enum": [ "pending", "submitted", "working", "completed", "failed", "canceled", "input_required", "auth_required", "rejected", "unknown" ] }, "targetNameSnapshot": { "type": "string" }, "interfaceSnapshot": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "errorCode": { "nullable": true, "type": "string" }, "statusReason": { "nullable": true, "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "parentAgentId", "connectionId", "toolId", "userId", "conversationId", "toolCallId", "messageId", "remoteTaskId", "remoteContextId", "state", "targetNameSnapshot", "interfaceSnapshot", "errorCode", "statusReason", "startedAt", "completedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } } }, "/v1/a2a/{agentId}/.well-known/agent.json": { "get": { "tags": [ "A2A" ], "description": "Get A2A AgentCard for an internal agent (must be agentType='agent')", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" }, "capabilities": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "stateTransitionHistory": { "type": "boolean" } }, "required": [ "streaming", "pushNotifications", "stateTransitionHistory" ], "additionalProperties": false }, "defaultInputModes": { "type": "array", "items": { "type": "string" } }, "defaultOutputModes": { "type": "array", "items": { "type": "string" } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "inputModes": { "type": "array", "items": { "type": "string" } }, "outputModes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "tags", "inputModes", "outputModes" ], "additionalProperties": false } } }, "required": [ "name", "description", "url", "version", "capabilities", "defaultInputModes", "defaultOutputModes", "skills" ], "additionalProperties": false } } } } } } }, "/v1/a2a/{agentId}": { "post": { "tags": [ "A2A" ], "description": "Execute A2A message on an internal agent (must be agentType='agent'). Accepts a JSON-RPC envelope or any JSON payload — non-JSON-RPC payloads are stringified and passed through to the agent as the user message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "method": { "type": "string" }, "params": { "type": "object", "properties": { "message": { "type": "object", "properties": { "parts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "kind", "text" ] } } } } } } }, "required": [ "jsonrpc", "id", "method" ] } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "result": { "type": "object", "properties": { "messageId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "agent" ] }, "parts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "kind", "text" ], "additionalProperties": false } }, "contextId": { "type": "string" }, "taskId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "messageId", "role", "parts" ], "additionalProperties": false }, "error": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id" ], "additionalProperties": false } } } } } } }, "/v2/a2a/agents": { "get": { "tags": [ "A2A" ], "description": "List the A2A AgentCards the presented credential is allowed to reach", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "documentationUrl": { "type": "string" }, "provider": { "type": "object", "properties": { "url": { "type": "string" }, "organization": { "type": "string" } }, "required": [ "url", "organization" ], "additionalProperties": false }, "supportedInterfaces": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "protocolBinding": { "type": "string" }, "protocolVersion": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false } }, "capabilities": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "extendedAgentCard": { "type": "boolean" } }, "required": [ "streaming", "pushNotifications", "extendedAgentCard" ], "additionalProperties": false }, "securitySchemes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "scheme": { "type": "string" }, "bearerFormat": { "type": "string" }, "description": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "securityRequirements": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "defaultInputModes": { "type": "array", "items": { "type": "string" } }, "defaultOutputModes": { "type": "array", "items": { "type": "string" } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "inputModes": { "type": "array", "items": { "type": "string" } }, "outputModes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "tags", "inputModes", "outputModes" ], "additionalProperties": false } } }, "required": [ "name", "description", "version", "provider", "supportedInterfaces", "capabilities", "securitySchemes", "securityRequirements", "defaultInputModes", "defaultOutputModes", "skills" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false } } } } } } }, "/v2/a2a/{agentId}/.well-known/agent-card.json": { "get": { "tags": [ "A2A" ], "description": "Get A2A AgentCard for an internal agent (must be agentType='agent')", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "documentationUrl": { "type": "string" }, "provider": { "type": "object", "properties": { "url": { "type": "string" }, "organization": { "type": "string" } }, "required": [ "url", "organization" ], "additionalProperties": false }, "supportedInterfaces": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "protocolBinding": { "type": "string" }, "protocolVersion": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false } }, "capabilities": { "type": "object", "properties": { "streaming": { "type": "boolean" }, "pushNotifications": { "type": "boolean" }, "extendedAgentCard": { "type": "boolean" } }, "required": [ "streaming", "pushNotifications", "extendedAgentCard" ], "additionalProperties": false }, "securitySchemes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "scheme": { "type": "string" }, "bearerFormat": { "type": "string" }, "description": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "securityRequirements": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "defaultInputModes": { "type": "array", "items": { "type": "string" } }, "defaultOutputModes": { "type": "array", "items": { "type": "string" } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "inputModes": { "type": "array", "items": { "type": "string" } }, "outputModes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "tags", "inputModes", "outputModes" ], "additionalProperties": false } } }, "required": [ "name", "description", "version", "provider", "supportedInterfaces", "capabilities", "securitySchemes", "securityRequirements", "defaultInputModes", "defaultOutputModes", "skills" ], "additionalProperties": false } } } }, "304": { "description": "Default Response" } } } }, "/v2/a2a/{agentId}": { "post": { "tags": [ "A2A" ], "description": "Main A2A JSON-RPC endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "method": { "type": "string" }, "params": {} }, "required": [ "jsonrpc", "id", "method" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "result": {}, "error": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id" ], "additionalProperties": false } } } } } } }, "/api/agent-catalog": { "get": { "operationId": "getAgentCatalog", "tags": [ "Agents" ], "description": "List internal and external A2A agents for the Agents page.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`agent:read`](/docs/reference/permissions#agent:read); when `status=deleted`, requires [`agent:delete`](/docs/reference/permissions#agent:delete). External A2A rows are limited to agents visible to the caller unless they have [`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update); when `selectableOnly=true`, external rows are omitted unless the caller has that permission.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false }, { "schema": { "type": "string", "enum": [ "personal", "team", "org", "built_in" ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeBuiltIn", "required": false, "description": "Also list the built-in agents. Applies to agent admins only, and the access filter does not apply to these agents." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "teamIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "authorIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "excludeAuthorIds", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonalAgents", "required": false }, { "schema": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false, "description": "Only these agents (comma-separated IDs), such as the viewer's automatic pins." }, { "schema": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "excludeIds", "required": false, "description": "Leave these agents out (comma-separated IDs), such as the ones the list already shows as automatic pins." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "type": "boolean" }, "in": "query", "name": "selectableOnly", "required": false, "description": "When true, omit external A2A agents unless the caller can manage external-agent settings. Used to enumerate rows for bulk selection on the Agents page." }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false }, { "schema": { "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "chat", "custom", "claude-code", "codex", "opencode", "hermes", "openclaw", "grok", "kimi", "copilot" ] }, "in": "query", "name": "runtime", "required": false }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "organization-default" ] } ] }, "in": "query", "name": "providerApiKeyId", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "pinned", "required": false, "description": "Filter internal agents by the current user's pins. Pinned results exclude external A2A agents and are ordered by newest pin first." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeTools", "required": false, "description": "Include each internal agent's assigned tools (default: true). Set `includeTools=false` for a smaller response when you only need agents or their counts. `toolsCount` and `subagentsCount` remain available; an empty `tools` array then means tools were omitted, not that none are assigned." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "name", "createdAt", "team", "toolsCount", "subagentsCount", "lastUsedAt" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "value": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "toolsCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Assigned tools other than subagent delegations, as the Agents and MCP Gateways pages count them. Always present, even when `tools` is not requested." }, "subagentsCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Agents this agent delegates to. Always present, even when `tools` is not requested." } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts", "pinnedAt", "toolsCount", "subagentsCount" ], "additionalProperties": false } }, "required": [ "type", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "external" ] }, "value": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "discoveryMode": { "type": "string", "enum": [ "well_known", "card_url", "inline_card" ] }, "discoveryUrl": { "nullable": true, "type": "string" }, "agentCard": { "type": "object", "additionalProperties": {} }, "cardHash": { "type": "string" }, "lastDiscoveredAt": { "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remoteAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "selectedInterface": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "protocolBinding": { "type": "string", "enum": [ "JSONRPC", "HTTP+JSON" ] }, "protocolVersion": { "type": "string", "minLength": 1 }, "tenant": { "type": "string" } }, "required": [ "url", "protocolBinding", "protocolVersion" ], "additionalProperties": false }, "securityRequirement": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key" ] }, "authConfig": { "type": "object", "properties": { "headerName": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "lastVerifiedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredential": { "type": "boolean" } }, "required": [ "id", "remoteAgentId", "selectedInterface", "securityRequirement", "authType", "authConfig", "enabled", "lastVerifiedAt", "createdAt", "updatedAt", "hasCredential" ], "additionalProperties": false }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "assignmentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "authorId", "name", "description", "discoveryMode", "discoveryUrl", "agentCard", "cardHash", "lastDiscoveredAt", "createdByServiceAccountId", "createdAt", "updatedAt", "connection", "toolId", "assignmentCount", "lastUsedAt", "authorName", "createdBy" ], "additionalProperties": false } }, "required": [ "type", "value" ], "additionalProperties": false } ] } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "agents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "externalAgents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "agents", "externalAgents" ], "additionalProperties": false } }, "required": [ "data", "pagination", "totals" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `agent:read`; when `status=deleted`, requires `agent:delete`. External A2A rows are limited to agents visible to the caller unless they have `organizationSettings:update`; when `selectableOnly=true`, external rows are omitted unless the caller has that permission.", "permissions": [] } } }, "/api/agents": { "get": { "operationId": "getAgents", "tags": [ "Agents" ], "description": "Get all agents with pagination, sorting, and filtering\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on agent type. `profile` and `agent` require [`agent:read`](/docs/reference/permissions#agent:read); `mcp_gateway` requires [`mcpGateway:read`](/docs/reference/permissions#mcpGateway:read). If no type filter is provided, the user must have read access to at least one agent type.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false, "description": "Filter by agent name" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeBuiltIn", "required": false, "description": "Include built-in agents, so ids assigned elsewhere still resolve. Only agent admins see them; ignored with `scope`." }, { "schema": { "type": "string", "enum": [ "chat" ] }, "in": "query", "name": "view", "required": false, "description": "`chat` keeps the system chat assistant in the list for chat selection." }, { "schema": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] }, "in": "query", "name": "agentType", "required": false, "description": "Filter by agent type. 'profile' = external API gateway profiles, 'mcp_gateway' = MCP gateway, 'agent' = internal agents with prompts." }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] } }, "in": "query", "name": "agentTypes", "required": false, "description": "Filter by multiple agent types (comma-separated). Takes precedence over agentType if both provided." }, { "schema": { "type": "string", "enum": [ "personal", "team", "org", "built_in" ] }, "in": "query", "name": "scope", "required": false, "description": "Filter by scope: personal, team, org, or built_in." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "teamIds", "required": false, "description": "Filter by specific team IDs (comma-separated). Only used when scope=team." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "authorIds", "required": false, "description": "Filter by author user IDs (comma-separated). Admin-only, only used when scope=personal." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "excludeAuthorIds", "required": false, "description": "Exclude agents by author user IDs (comma-separated). Admin-only, only used when scope=personal." }, { "schema": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false, "description": "Only these agents (comma-separated IDs), such as the viewer's automatic pins." }, { "schema": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "excludeIds", "required": false, "description": "Leave these agents out (comma-separated IDs), such as the ones the list already shows as automatic pins." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonalAgents", "required": false, "description": "Hide personal agents owned by other users. Admin-only; no-op for non-admins." }, { "schema": { "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. Deleted rows require delete permission." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeActivationSkillsCount", "required": false, "description": "Include the caller-relative activation skill count used by internal-agent cards. Omitted when the caller lacks skill:read." }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "organization-default" ] } ] }, "in": "query", "name": "providerApiKeyId", "required": false, "description": "Filter by a configured provider key, or organization-default for agents with no pinned key or model." }, { "schema": { "type": "boolean" }, "in": "query", "name": "pinned", "required": false, "description": "Filter by the current user's pins. Pinned results are ordered by newest pin first; unpinned results keep the requested sort." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeTools", "required": false, "description": "Include assigned tools (default: true). Set `includeTools=false` for a smaller response when you only need agents or their counts. `toolsCount` and `subagentsCount` remain available; an empty `tools` array then means tools were omitted, not that none are assigned." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeTotal", "required": false, "description": "Count every matching agent for `pagination.total`. Defaults to true. Pass false from lists that never show a total, such as pinned rows. With false, the count is skipped and `hasNext` stays exact. `total` is then a lower bound: the agents up to this page, plus one when more follow." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "name", "createdAt", "toolsCount", "subagentsCount", "knowledgeSourcesCount", "team", "lastUsedAt" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "toolsCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Assigned tools other than subagent delegations, as the Agents and MCP Gateways pages count them. Always present, even when `tools` is not requested." }, "subagentsCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Agents this agent delegates to. Always present, even when `tools` is not requested." } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts", "pinnedAt", "toolsCount", "subagentsCount" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on agent type. `profile` and `agent` require `agent:read`; `mcp_gateway` requires `mcpGateway:read`. If no type filter is provided, the user must have read access to at least one agent type.", "permissions": [] } }, "post": { "operationId": "createAgent", "tags": [ "Agents" ], "description": "Create a new agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the agent type being created. `profile` and `agent` require [`agent:create`](/docs/reference/permissions#agent:create); `mcp_gateway` requires [`mcpGateway:create`](/docs/reference/permissions#mcpGateway:create). Grants on the agent may further restrict the request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$" } }, "allowedCidrs": { "maxItems": 500, "type": "array", "items": { "type": "string" } } } }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ] } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ] }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ] }, "passthroughHeaders": { "nullable": true, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$" } }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 1, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } } }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ] } ] }, "deletedAt": { "nullable": true }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "knowledgeBaseIds": { "default": [], "type": "array", "items": { "type": "string" } }, "connectorIds": { "default": [], "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ] } }, "activationSkillPolicy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "manual" ] }, "allowedReferences": { "default": [], "maxItems": 1000, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ] } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } }, "excludedReferences": { "default": [], "maxItems": 1000, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ] } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } } }, "required": [ "mode" ] }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "scope": { "not": {} }, "teams": { "not": {} }, "users": { "not": {} } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the agent type being created. `profile` and `agent` require `agent:create`; `mcp_gateway` requires `mcpGateway:create`. Grants on the agent may further restrict the request.", "permissions": [] } } }, "/api/agents/{id}/pin": { "put": { "operationId": "pinAgent", "tags": [ "Agents" ], "description": "Pin an agent for the current user. Personal — does not affect other members. Any user who can read the agent may pin it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the target agent's type and the caller's visibility. `profile` and `agent` require [`agent:read`](/docs/reference/permissions#agent:read); `mcp_gateway` requires [`mcpGateway:read`](/docs/reference/permissions#mcpGateway:read).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the target agent's type and the caller's visibility. `profile` and `agent` require `agent:read`; `mcp_gateway` requires `mcpGateway:read`.", "permissions": [] } }, "delete": { "operationId": "unpinAgent", "tags": [ "Agents" ], "description": "Remove the current user's pin on an agent. Idempotent and intentionally has no visibility check so stale pins can still be cleared.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/chat-roster": { "get": { "operationId": "getChatAgentRoster", "tags": [ "Agents" ], "description": "Get authorized chat agent identities and model references. With `bootstrap`, the starting roster plus the caller's and the organization's default agents the caller can use.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`agent:read`](/docs/reference/permissions#agent:read); only internal agents visible to the caller are returned.", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "bootstrap", "required": false }, { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "builtIn": { "nullable": true, "type": "boolean" }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sharedByName": { "type": "boolean" } }, "required": [ "id", "organizationId", "name", "description", "icon", "scope", "authorId", "agentType", "builtIn", "builtInAgentConfig", "runtime", "modelId", "llmApiKeyId", "modelPoolId", "autoRouterId", "sharedByName" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `agent:read`; only internal agents visible to the caller are returned.", "permissions": [] } } }, "/api/agents/chat-roster/page": { "get": { "operationId": "getChatAgentRosterPage", "tags": [ "Agents" ], "description": "Fetch bounded authorized chat choices with literal name or description search.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "createdAt", "name", "chat" ] }, "in": "query", "name": "sortBy", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "builtIn": { "nullable": true, "type": "boolean" }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sharedByName": { "type": "boolean" } }, "required": [ "id", "organizationId", "name", "description", "icon", "scope", "authorId", "agentType", "builtIn", "builtInAgentConfig", "runtime", "modelId", "llmApiKeyId", "modelPoolId", "autoRouterId", "sharedByName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/options": { "get": { "operationId": "getAgentOptions", "tags": [ "Agents" ], "description": "List authorized agent options one page at a time. Filter by up to 200 IDs; pages hold up to 1,000 items.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on agent type. `profile` and `agent` require [`agent:read`](/docs/reference/permissions#agent:read); `mcp_gateway` requires [`mcpGateway:read`](/docs/reference/permissions#mcpGateway:read). If no type filter is provided, the user must have read access to at least one agent type.", "parameters": [ { "schema": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] }, "in": "query", "name": "agentType", "required": false, "description": "Filter by agent type. 'profile' = external API gateway profiles, 'mcp_gateway' = MCP gateway, 'agent' = internal agents with prompts." }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] } }, "in": "query", "name": "agentTypes", "required": false, "description": "Filter by multiple agent types (comma-separated). Takes precedence over agentType if both provided." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeBuiltIn", "required": false, "description": "Exclude built-in agents from the results, except the system chat assistant in chat view. Defaults to false." }, { "schema": { "type": "string", "enum": [ "personal", "team", "org", "built_in" ] }, "in": "query", "name": "scope", "required": false, "description": "Filter by scope: personal, team, org, or built_in." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonalAgents", "required": false, "description": "Hide personal agents owned by other users. Admin-only; no-op for non-admins (their access control already excludes them)." }, { "schema": { "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. Deleted rows require delete permission." }, { "schema": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "isPersonalGateway": { "type": "boolean" }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "description": { "nullable": true, "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id", "name", "slug", "agentType", "icon", "scope", "authorId", "isPersonalGateway", "runtime", "description", "teams", "users" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on agent type. `profile` and `agent` require `agent:read`; `mcp_gateway` requires `mcpGateway:read`. If no type filter is provided, the user must have read access to at least one agent type.", "permissions": [] } } }, "/api/agents/options/page": { "get": { "operationId": "getAgentOptionsPage", "tags": [ "Agents" ], "description": "Fetch a bounded authorized agent selector page with server-side search and eligibility filters.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] }, "in": "query", "name": "agentType", "required": false, "description": "Filter by agent type. 'profile' = external API gateway profiles, 'mcp_gateway' = MCP gateway, 'agent' = internal agents with prompts." }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] } }, "in": "query", "name": "agentTypes", "required": false, "description": "Filter by multiple agent types (comma-separated). Takes precedence over agentType if both provided." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeBuiltIn", "required": false, "description": "Exclude built-in agents from the results, except the system chat assistant in chat view. Defaults to false." }, { "schema": { "type": "string", "enum": [ "personal", "team", "org", "built_in" ] }, "in": "query", "name": "scope", "required": false, "description": "Filter by scope: personal, team, org, or built_in." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonalAgents", "required": false, "description": "Hide personal agents owned by other users. Admin-only; no-op for non-admins (their access control already excludes them)." }, { "schema": { "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. Deleted rows require delete permission." }, { "schema": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "name", "selector", "name_or_description" ] }, "in": "query", "name": "searchMode", "required": false }, { "schema": { "type": "string", "enum": [ "createdAt", "name" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "exactName", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "authorId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "excludeIds", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "runtimeCommand", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "onlyOwnPersonalAgents", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludePersonalGateways", "required": false }, { "schema": { "type": "string", "enum": [ "none", "organization", "team", "user" ] }, "in": "query", "name": "audienceVisibility", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "audienceTeamIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "audienceUserIds", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "audienceEditorIsOwner", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "isPersonalGateway": { "type": "boolean" }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "description": { "nullable": true, "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "id", "name", "slug", "agentType", "icon", "scope", "authorId", "isPersonalGateway", "runtime", "description", "teams", "users" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/options/ids": { "get": { "operationId": "getAgentOptionIds", "tags": [ "Agents" ], "description": "Fetch complete authorized selector IDs for an explicit select-all action without presentation metadata.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] }, "in": "query", "name": "agentType", "required": false, "description": "Filter by agent type. 'profile' = external API gateway profiles, 'mcp_gateway' = MCP gateway, 'agent' = internal agents with prompts." }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "profile", "mcp_gateway", "agent" ] } }, "in": "query", "name": "agentTypes", "required": false, "description": "Filter by multiple agent types (comma-separated). Takes precedence over agentType if both provided." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeBuiltIn", "required": false, "description": "Exclude built-in agents from the results, except the system chat assistant in chat view. Defaults to false." }, { "schema": { "type": "string", "enum": [ "personal", "team", "org", "built_in" ] }, "in": "query", "name": "scope", "required": false, "description": "Filter by scope: personal, team, org, or built_in." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonalAgents", "required": false, "description": "Hide personal agents owned by other users. Admin-only; no-op for non-admins (their access control already excludes them)." }, { "schema": { "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. Deleted rows require delete permission." }, { "schema": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "name", "selector", "name_or_description" ] }, "in": "query", "name": "searchMode", "required": false }, { "schema": { "type": "string", "enum": [ "createdAt", "name" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "exactName", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "authorId", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "excludeIds", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "runtimeCommand", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "onlyOwnPersonalAgents", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludePersonalGateways", "required": false }, { "schema": { "type": "string", "enum": [ "none", "organization", "team", "user" ] }, "in": "query", "name": "audienceVisibility", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "audienceTeamIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "audienceUserIds", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "audienceEditorIsOwner", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/credential-readiness": { "get": { "operationId": "getAgentCredentialReadiness", "tags": [ "Agents" ], "description": "For each internal agent that enforces a missing-credential behavior, the MCP servers the calling user has no usable connection to\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "maxItems": 200, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "missingConnections": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "catalogName": { "type": "string" } }, "required": [ "catalogId", "catalogName" ], "additionalProperties": false } } }, "required": [ "agentId", "missingCredentialBehavior", "missingConnections" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/mcp-gateways/default": { "get": { "operationId": "getDefaultMcpGateway", "tags": [ "MCP Gateway" ], "description": "Get the caller's personal MCP Gateway, creating it on first use.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpGateway:read`](/docs/reference/permissions#mcpGateway:read): Open MCP Gateways", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "includeTools", "required": false, "description": "Include assigned tools (default: true). Set `includeTools=false` for a smaller response when you only need the gateway or its counts. `toolsCount` and `subagentsCount` remain available; an empty `tools` array then means tools were omitted, not that none are assigned. `sandboxAvailable` is omitted too." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "toolsCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Assigned tools other than subagent delegations, as the Agents and MCP Gateways pages count them. Always present, even when `tools` is not requested." }, "subagentsCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Agents this agent delegates to. Always present, even when `tools` is not requested." } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts", "toolsCount", "subagentsCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpGateway:read" ] } } }, "/api/agents/import": { "post": { "operationId": "importAgent", "tags": [ "Agents" ], "description": "Import an agent from a portable JSON payload. Creates a new agent with all resolvable associations and returns soft warnings for any references that could not be found.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "enum": [ "1" ], "description": "Schema version for forward compatibility" }, "exportedAt": { "type": "string", "description": "ISO 8601 timestamp" }, "sourceInstance": { "description": "Informational: hostname of the source instance", "nullable": true, "type": "string" }, "agent": { "type": "object", "properties": { "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "agent" ], "description": "Only internal agents are exportable" }, "description": { "nullable": true, "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "Original scope; imports always default to personal" }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "default": false, "type": "boolean" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "passthroughHeaders": { "nullable": true, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$" } } }, "required": [ "name", "agentType", "description", "systemPrompt", "icon", "scope", "toolExposureMode", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain" ] }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "suggestedPrompts": { "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "summaryTitle", "prompt" ] } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "description": "Tool name as registered in the MCP catalog" }, "catalogName": { "nullable": true, "description": "MCP catalog item name (null for proxy-sniffed tools)", "type": "string" }, "credentialResolutionMode": { "description": "How credentials are resolved for this tool assignment", "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "toolName", "catalogName" ] } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "targetAgentName": { "type": "string", "description": "Name of the target agent for delegation" } }, "required": [ "targetAgentName" ] } }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Knowledge base name" } }, "required": [ "name" ] } }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Connector name" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ], "description": "Connector type (e.g. confluence, github)" } }, "required": [ "name", "connectorType" ] } } }, "required": [ "version", "exportedAt", "agent", "labels", "suggestedPrompts", "tools", "delegations", "knowledgeBases", "connectors" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool", "knowledgeBase", "connector", "delegation" ] }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "name", "message" ], "additionalProperties": false } } }, "required": [ "agent", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}": { "get": { "operationId": "getAgent", "tags": [ "Agents" ], "description": "Get agent by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the target agent's type. `profile` and `agent` require [`agent:read`](/docs/reference/permissions#agent:read); `mcp_gateway` requires [`mcpGateway:read`](/docs/reference/permissions#mcpGateway:read).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the target agent's type. `profile` and `agent` require `agent:read`; `mcp_gateway` requires `mcpGateway:read`.", "permissions": [] } }, "put": { "operationId": "updateAgent", "tags": [ "Agents" ], "description": "Update an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the target agent's type. `profile` and `agent` require `agent:update`; `mcp_gateway` requires `mcpGateway:update`. Grants on the agent may further restrict the request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$" } }, "allowedCidrs": { "maxItems": 500, "type": "array", "items": { "type": "string" } } } }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ] } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ] }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ] }, "passthroughHeaders": { "nullable": true, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "repositories": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 140, "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\\/(?:[A-Za-z0-9._-]{1,100}|\\*)$" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 400, "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\\/[A-Za-z0-9._-]{1,100}\\/\\.github\\/workflows\\/[A-Za-z0-9._/-]+\\.ya?ml@(?:refs\\/heads\\/[^\\s@]+|refs\\/tags\\/[^\\s@]+|[0-9a-f]{40})$" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 1, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } } }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ] } ] }, "deletedAt": { "nullable": true }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ] } }, "scope": { "not": {} }, "teams": { "not": {} }, "users": { "not": {} } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the target agent's type. `profile` and `agent` require `agent:update`; `mcp_gateway` requires `mcpGateway:update`. Grants on the agent may further restrict the request.", "permissions": [] } }, "delete": { "operationId": "deleteAgent", "tags": [ "Agents" ], "description": "Delete an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the target agent's type. `profile` and `agent` require [`agent:delete`](/docs/reference/permissions#agent:delete); `mcp_gateway` requires [`mcpGateway:delete`](/docs/reference/permissions#mcpGateway:delete). Additional scope checks may apply.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the target agent's type. `profile` and `agent` require `agent:delete`; `mcp_gateway` requires `mcpGateway:delete`. Additional scope checks may apply.", "permissions": [] } } }, "/api/agents/{id}/identity-bindings": { "get": { "operationId": "getAgentIdentityBindings", "tags": [ "Agents" ], "description": "Get the identities an agent acts as at identity providers\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "identityProviderId": { "type": "string", "minLength": 1 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "identityProviderId", "externalId" ], "additionalProperties": false } } }, "required": [ "bindings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "replaceAgentIdentityBindings", "tags": [ "Agents" ], "description": "Replace the identities an agent acts as at identity providers. Changing them requires identityProvider:update.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "identityProviderId": { "type": "string", "minLength": 1 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "identityProviderId", "externalId" ] } } }, "required": [ "bindings" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "identityProviderId": { "type": "string", "minLength": 1 }, "externalId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "identityProviderId", "externalId" ], "additionalProperties": false } } }, "required": [ "bindings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/default-suggested-prompts": { "get": { "operationId": "getAgentDefaultSuggestedPrompts", "tags": [ "Agents" ], "description": "Suggested prompts the platform offers for an agent that has none of its own. They are not stored on the agent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/versions": { "get": { "operationId": "getAgentVersions", "tags": [ "Agents" ], "description": "List an agent's config version history, newest first, as metadata only (no snapshot). Retention keeps the last 100 versions, so the oldest listed version may be greater than 1.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "contentHash": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "version", "contentHash", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/versions/{version}": { "get": { "operationId": "getAgentVersion", "tags": [ "Agents" ], "description": "Get one immutable agent config version (full snapshot; key material is never captured). Versions dropped by retention are 404.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "snapshot": { "type": "object", "properties": { "agentType": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "toolExposureMode": { "type": "string" }, "missingCredentialBehavior": { "default": "allow", "type": "string" }, "accessAllTools": { "type": "boolean" }, "accessAllSubagents": { "type": "boolean" }, "activationSkillMode": { "default": "all", "type": "string", "enum": [ "all", "manual" ] }, "passthroughHeaders": { "type": "array", "items": { "type": "string" } }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string" }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "builtInAgentConfig": {}, "model": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" } }, "required": [ "id", "externalId" ], "additionalProperties": false }, "llmApiKey": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name", "provider" ], "additionalProperties": false }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string" }, "networkPolicy": { "default": null, "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "subagentLoadBalancing": { "default": null, "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "tools": { "type": "array", "items": { "type": "object", "properties": { "toolId": { "type": "string" }, "name": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "credentialResolutionMode": { "type": "string" } }, "required": [ "toolId", "name", "mcpServerId", "credentialResolutionMode" ], "additionalProperties": false } }, "excludedTools": { "type": "array", "items": { "type": "object", "properties": { "toolId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "toolId", "name" ], "additionalProperties": false } }, "excludedSubagents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "agentId", "name" ], "additionalProperties": false } }, "suggestedPrompts": { "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "fileName": { "type": "string" }, "content": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } }, "required": [ "event", "fileName", "content", "requirements", "enabled" ], "additionalProperties": false } }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "excludedConnectors": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "activationSkillRuleCounts": { "type": "object", "properties": { "allowed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "excluded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "allowed", "excluded" ], "additionalProperties": false }, "activationSkillRuleDigest": { "type": "string", "minLength": 64, "maxLength": 64 } }, "required": [ "agentType", "name", "description", "icon", "systemPrompt", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSubagents", "activationSkillMode", "passthroughHeaders", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "builtInAgentConfig", "model", "llmApiKey", "identityProviderId", "environmentId", "networkPolicy", "subagentLoadBalancing", "tools", "excludedTools", "excludedSubagents", "suggestedPrompts", "hooks", "knowledgeBases", "connectors", "excludedConnectors", "activationSkillRuleCounts", "activationSkillRuleDigest" ], "additionalProperties": false }, "contentHash": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "version", "snapshot", "contentHash", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/versions/{version}/restore": { "post": { "operationId": "restoreAgentVersion", "tags": [ "Agents" ], "description": "Restore an agent's config to an earlier version by replaying its snapshot forward as a new head version — history is never rewritten. All-or-nothing: the restore is validated in full before anything is written, and a version referencing something that no longer exists or is out of the caller's reach (a deleted tool, key or knowledge source) is rejected with 400 rather than partially applied. Only differences from the agent's live config are written, so restoring the current configuration is a no-op. Retrying is safe: the source version is immutable, and the pre-restore config is forked as a version before anything is written.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "baseVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/clone": { "post": { "operationId": "cloneAgent", "tags": [ "Agents" ], "description": "Clone an agent and its associations with explicit permission grants. The creator receives full access; source sharing is not copied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "scope": { "not": {} }, "teams": { "not": {} }, "users": { "not": {} } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/export": { "get": { "operationId": "exportAgent", "tags": [ "Agents" ], "description": "Export an agent configuration as a portable JSON payload for cross-instance transfer\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "enum": [ "1" ], "description": "Schema version for forward compatibility" }, "exportedAt": { "type": "string", "description": "ISO 8601 timestamp" }, "sourceInstance": { "description": "Informational: hostname of the source instance", "nullable": true, "type": "string" }, "agent": { "type": "object", "properties": { "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "agent" ], "description": "Only internal agents are exportable" }, "description": { "nullable": true, "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "Original scope; imports always default to personal" }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "default": false, "type": "boolean" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "passthroughHeaders": { "nullable": true, "maxItems": 20, "type": "array", "items": {} } }, "required": [ "name", "agentType", "description", "systemPrompt", "icon", "scope", "toolExposureMode", "accessAllTools", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "suggestedPrompts": { "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string" }, "prompt": { "type": "string" } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "toolName": { "type": "string", "description": "Tool name as registered in the MCP catalog" }, "catalogName": { "nullable": true, "description": "MCP catalog item name (null for proxy-sniffed tools)", "type": "string" }, "credentialResolutionMode": { "description": "How credentials are resolved for this tool assignment", "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "toolName", "catalogName" ], "additionalProperties": false } }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "targetAgentName": { "type": "string", "description": "Name of the target agent for delegation" } }, "required": [ "targetAgentName" ], "additionalProperties": false } }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Knowledge base name" } }, "required": [ "name" ], "additionalProperties": false } }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Connector name" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ], "description": "Connector type (e.g. confluence, github)" } }, "required": [ "name", "connectorType" ], "additionalProperties": false } } }, "required": [ "version", "exportedAt", "agent", "labels", "suggestedPrompts", "tools", "delegations", "knowledgeBases", "connectors" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/mcp-tool-preview": { "get": { "operationId": "getAgentMcpToolPreview", "tags": [ "Agents" ], "description": "Preview the gateway's initial tools/list for the current user, with estimated tool-definition context tokens\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": "generic", "type": "string", "enum": [ "claude-code", "generic" ] }, "in": "query", "name": "client", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "tokenCount": { "oneOf": [ { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "enum": [ "claude-provider" ] }, "model": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "total", "source", "model", "observedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "source": { "type": "string", "enum": [ "estimate" ] }, "model": { "type": "string", "nullable": true, "enum": [ null ] }, "observedAt": { "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "total", "source", "model", "observedAt" ], "additionalProperties": false } ] }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "catalogId": { "nullable": true, "type": "string" }, "tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "description", "catalogId", "tokens" ], "additionalProperties": false } } }, "required": [ "toolExposureMode", "tokenCount", "tools" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/tool-exclusions": { "get": { "operationId": "getAgentToolExclusions", "tags": [ "Agents" ], "description": "Get the agent's Auto-tool-mode exclusions: MCP catalogs and individual tools removed from its tool surface while 'access all tools' is on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedToolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Individual tool IDs excluded from the agent's surface" } }, "required": [ "excludedToolIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateAgentToolExclusions", "tags": [ "Agents" ], "description": "Replace the agent's Auto-tool-mode exclusions (full replace of the excluded tool set)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedToolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Individual tool IDs excluded from the agent's surface" } }, "required": [ "excludedToolIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedToolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Individual tool IDs excluded from the agent's surface" } }, "required": [ "excludedToolIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/subagent-exclusions": { "get": { "operationId": "getAgentSubagentExclusions", "tags": [ "Agents" ], "description": "Get the agent's Auto-subagent-mode exclusions: delegation target agents removed from its Auto delegation surface while 'access all subagents' is on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedSubagentIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Target agent IDs excluded from the agent's Auto delegation surface" } }, "required": [ "excludedSubagentIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateAgentSubagentExclusions", "tags": [ "Agents" ], "description": "Replace the agent's Auto-subagent-mode exclusions (full replace of the excluded delegation-target set)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedSubagentIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Target agent IDs excluded from the agent's Auto delegation surface" } }, "required": [ "excludedSubagentIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedSubagentIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Target agent IDs excluded from the agent's Auto delegation surface" } }, "required": [ "excludedSubagentIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/knowledge-source-exclusions": { "get": { "operationId": "getAgentKnowledgeSourceExclusions", "tags": [ "Agents" ], "description": "Get the agent's Auto-mode knowledge-source exclusions: knowledge connectors removed from the surface its knowledge queries span while 'access all tools' is on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedConnectorIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Knowledge connector IDs excluded from the agent's Auto knowledge surface" } }, "required": [ "excludedConnectorIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "put": { "operationId": "updateAgentKnowledgeSourceExclusions", "tags": [ "Agents" ], "description": "Replace the agent's Auto-mode knowledge-source exclusions (full replace of the excluded knowledge-connector set)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedConnectorIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Knowledge connector IDs excluded from the agent's Auto knowledge surface" } }, "required": [ "excludedConnectorIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedConnectorIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Knowledge connector IDs excluded from the agent's Auto knowledge surface" } }, "required": [ "excludedConnectorIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/agents/activation-skills": { "get": { "operationId": "getAgentActivationSkills", "tags": [ "Agents" ], "description": "List a paginated, searchable view of effective or policy-eligible skills for an internal agent or draft\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Case-insensitive substring match on skill name, activation name, description, or provider name." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "agentId", "required": false, "description": "Existing internal agent to evaluate. Omit to preview a new agent." }, { "schema": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "environmentId", "required": false, "description": "Environment preview override for a draft or pending edit. Omit to use the saved agent environment, or the Default environment for a new draft." }, { "schema": { "default": "effective", "type": "string", "enum": [ "effective", "eligible" ] }, "in": "query", "name": "view", "required": false, "description": "Effective applies the saved agent policy; eligible lists caller-visible choices for the policy editor." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "reference": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." }, "name": { "type": "string", "description": "The declared, human-facing skill name." }, "activationName": { "type": "string", "description": "The exact name to pass to load_skill." }, "description": { "type": "string", "description": "The skill description." }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "The visibility scope through which the skill is shared." }, "providerName": { "nullable": true, "description": "Plugin or MCP server name; null for a skill-library entry.", "type": "string" } }, "required": [ "reference", "name", "activationName", "description", "scope", "providerName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "enabled": { "type": "boolean", "description": "Whether load_skill is available for this agent or draft. Effective results are empty when false; eligible policy-editor previews may still contain candidates." } }, "required": [ "data", "pagination", "enabled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/agents/{id}/activation-skill-policy": { "get": { "operationId": "getAgentActivationSkillPolicy", "tags": [ "Agents" ], "description": "Get an internal agent's skill activation policy\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "manual" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "allowedReferences": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } }, "excludedReferences": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } }, "allowedSkills": { "type": "array", "items": { "type": "object", "properties": { "reference": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." }, "name": { "type": "string", "description": "The declared, human-facing skill name." }, "activationName": { "type": "string", "description": "The exact name to pass to load_skill." }, "description": { "type": "string", "description": "The skill description." }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "The visibility scope through which the skill is shared." }, "providerName": { "nullable": true, "description": "Plugin or MCP server name; null for a skill-library entry.", "type": "string" } }, "required": [ "reference", "name", "activationName", "description", "scope", "providerName" ], "additionalProperties": false } }, "excludedSkills": { "type": "array", "items": { "type": "object", "properties": { "reference": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." }, "name": { "type": "string", "description": "The declared, human-facing skill name." }, "activationName": { "type": "string", "description": "The exact name to pass to load_skill." }, "description": { "type": "string", "description": "The skill description." }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "The visibility scope through which the skill is shared." }, "providerName": { "nullable": true, "description": "Plugin or MCP server name; null for a skill-library entry.", "type": "string" } }, "required": [ "reference", "name", "activationName", "description", "scope", "providerName" ], "additionalProperties": false } }, "hiddenAllowedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hiddenExcludedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "mode", "revision", "allowedReferences", "excludedReferences", "allowedSkills", "excludedSkills", "hiddenAllowedCount", "hiddenExcludedCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } }, "patch": { "operationId": "patchAgentActivationSkillPolicy", "tags": [ "Agents" ], "description": "Apply a revisioned update to an internal agent's skill activation policy\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mode": { "type": "string", "enum": [ "all", "manual" ] }, "operations": { "default": [], "maxItems": 2000, "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add", "remove" ] }, "disposition": { "type": "string", "enum": [ "allow", "exclude" ] }, "reference": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ] } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } }, "required": [ "op", "disposition", "reference" ] } }, "discardUnavailable": { "default": [], "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "allow", "exclude" ] } } }, "required": [ "expectedRevision" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all", "manual" ] }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "allowedReferences": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } }, "excludedReferences": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." } }, "allowedSkills": { "type": "array", "items": { "type": "object", "properties": { "reference": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." }, "name": { "type": "string", "description": "The declared, human-facing skill name." }, "activationName": { "type": "string", "description": "The exact name to pass to load_skill." }, "description": { "type": "string", "description": "The skill description." }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "The visibility scope through which the skill is shared." }, "providerName": { "nullable": true, "description": "Plugin or MCP server name; null for a skill-library entry.", "type": "string" } }, "required": [ "reference", "name", "activationName", "description", "scope", "providerName" ], "additionalProperties": false } }, "excludedSkills": { "type": "array", "items": { "type": "object", "properties": { "reference": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "native" ], "description": "A skill-library skill." }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The skill-library skill ID." } }, "required": [ "source", "skillId" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ], "description": "A skill from an MCP server." }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The MCP server installation ID." }, "uri": { "type": "string", "description": "The skill resource URI." } }, "required": [ "source", "mcpServerId", "uri" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ], "description": "A skill bundled in a plugin." }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The plugin ID." }, "skillPath": { "type": "string", "description": "The skill root inside the plugin." } }, "required": [ "source", "pluginId", "skillPath" ], "additionalProperties": false } ], "description": "Stable source identity: native uses skillId, external_mcp uses mcpServerId and uri, and plugin uses pluginId and skillPath." }, "name": { "type": "string", "description": "The declared, human-facing skill name." }, "activationName": { "type": "string", "description": "The exact name to pass to load_skill." }, "description": { "type": "string", "description": "The skill description." }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ], "description": "The visibility scope through which the skill is shared." }, "providerName": { "nullable": true, "description": "Plugin or MCP server name; null for a skill-library entry.", "type": "string" } }, "required": [ "reference", "name", "activationName", "description", "scope", "providerName" ], "additionalProperties": false } }, "hiddenAllowedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hiddenExcludedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "mode", "revision", "allowedReferences", "excludedReferences", "allowedSkills", "excludedSkills", "hiddenAllowedCount", "hiddenExcludedCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/agents/{id}/skills": { "get": { "operationId": "getAgentSkills", "tags": [ "Agents" ], "description": "Get the skills this gateway publishes over MCP: the explicitly assigned set, plus whether Auto mode ('access all skills') is on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessAllSkills": { "type": "boolean", "description": "Auto mode: expose every org-scoped skill visible in the agent's environment" }, "skillIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Skills explicitly assigned to the agent (Custom mode)" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "templated": { "type": "boolean" }, "agentName": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "scope", "templated", "agentName", "authorId" ], "additionalProperties": false }, "description": "The assigned skills themselves, in `skillIds` order" } }, "required": [ "accessAllSkills", "skillIds", "skills" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } }, "put": { "operationId": "updateAgentSkills", "tags": [ "Agents" ], "description": "Replace the skills this gateway publishes over MCP (full replace of the assigned set) and set Auto mode\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accessAllSkills": { "type": "boolean", "description": "Auto mode: expose every org-scoped skill visible in the agent's environment" }, "skillIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Skills explicitly assigned to the agent (Custom mode)" } }, "required": [ "accessAllSkills", "skillIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessAllSkills": { "type": "boolean", "description": "Auto mode: expose every org-scoped skill visible in the agent's environment" }, "skillIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Skills explicitly assigned to the agent (Custom mode)" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "templated": { "type": "boolean" }, "agentName": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "scope", "templated", "agentName", "authorId" ], "additionalProperties": false }, "description": "The assigned skills themselves, in `skillIds` order" } }, "required": [ "accessAllSkills", "skillIds", "skills" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/agents/{id}/skill-exclusions": { "get": { "operationId": "getAgentSkillExclusions", "tags": [ "Agents" ], "description": "Get the agent's Auto-skill-mode exclusions: skills removed from its published skill surface while 'access all skills' is on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedSkillIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Individual skill IDs excluded from the agent's skill surface" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "templated": { "type": "boolean" }, "agentName": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "scope", "templated", "agentName", "authorId" ], "additionalProperties": false }, "description": "The excluded skills themselves, in `excludedSkillIds` order" } }, "required": [ "excludedSkillIds", "skills" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } }, "put": { "operationId": "updateAgentSkillExclusions", "tags": [ "Agents" ], "description": "Replace the agent's Auto-skill-mode exclusions (full replace of the excluded skill set)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedSkillIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Individual skill IDs excluded from the agent's skill surface" } }, "required": [ "excludedSkillIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "excludedSkillIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Individual skill IDs excluded from the agent's skill surface" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "templated": { "type": "boolean" }, "agentName": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "scope", "templated", "agentName", "authorId" ], "additionalProperties": false }, "description": "The excluded skills themselves, in `excludedSkillIds` order" } }, "required": [ "excludedSkillIds", "skills" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/agents/{id}/transfer-ownership": { "post": { "operationId": "transferAgentOwnership", "tags": [ "Agents" ], "description": "Transfer an agent or MCP gateway to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/bulk": { "delete": { "operationId": "bulkDeleteAgents", "tags": [ "Agents" ], "description": "Soft-delete several agents in one request. Each id is authorized exactly as the single-agent delete authorizes its own, so an id the caller cannot see or modify — and a built-in agent or personal MCP gateway, which are never deletable — is reported in `failed` while the rest of the batch still applies. Deleted agents can be restored from the trash. Members who chose one as their personal default, and projects pinning it, are unpinned, as they are on the single-agent delete.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/restore": { "post": { "operationId": "restoreAgent", "tags": [ "Agents" ], "description": "Restore a soft-deleted agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the target agent's type. `profile` and `agent` require [`agent:delete`](/docs/reference/permissions#agent:delete); `mcp_gateway` requires [`mcpGateway:delete`](/docs/reference/permissions#mcpGateway:delete). Additional scope checks may apply.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the target agent's type. `profile` and `agent` require `agent:delete`; `mcp_gateway` requires `mcpGateway:delete`. Additional scope checks may apply.", "permissions": [] } } }, "/api/agents/{id}/permanent": { "delete": { "operationId": "permanentlyDeleteAgent", "tags": [ "Agents" ], "description": "Permanently destroy a soft-deleted agent. Global admins only — an [`agent:delete`](/docs/reference/permissions#agent:delete) or `agent:admin` grant reaches the trash, not past it. Irreversible, with no grace period: the agent's configuration and scheduled runs are destroyed, and it is cleared from the organization, /connection, and member defaults. Its history survives, detached — conversations and LLM usage rows are kept and simply stop pointing at it. 404 if there is no soft-deleted agent with that id in the org, which is also the answer when the agent is still live or the caller is not a global admin. Restore wins a race.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRestricted to the built-in Admin and Platform Admin roles. No permission grants it: [`agent:delete`](/docs/reference/permissions#agent:delete) and even `agent:admin` reach the trash, not past it, and a service account never qualifies. A caller without it gets 404, not 403, so the endpoint never confirms the agent exists.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Restricted to the built-in Admin and Platform Admin roles. No permission grants it: `agent:delete` and even `agent:admin` reach the trash, not past it, and a service account never qualifies. A caller without it gets 404, not 403, so the endpoint never confirms the agent exists.", "permissions": [] } } }, "/api/agents/labels/keys": { "get": { "operationId": "getLabelKeys", "tags": [ "Agents" ], "description": "Get all available label keys\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/labels/values": { "get": { "operationId": "getLabelValues", "tags": [ "Agents" ], "description": "Get all available label values\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/members/default-agent": { "get": { "operationId": "getMemberDefaultAgent", "tags": [ "Members" ], "description": "Get the current user's default agent ID, and their personal chat agent (the oldest live personal agent they authored), if any\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "personalChatAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "defaultAgentId", "personalChatAgentId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateMemberDefaultAgent", "tags": [ "Members" ], "description": "Set or clear the current user's default agent. Any chat agent the caller can see may be pinned — their own, a team's, or an organization-wide one — and it is preselected for their new chats ahead of the organization default. Null clears it, so the organization default applies. Nothing else writes this: a member who never pinned one has no personal default, and the organization default reaches them.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "defaultAgentId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "defaultAgentId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/{taskId}/workspace/files": { "get": { "operationId": "readAgentWorkspaceFile", "tags": [ "Agents" ], "description": "Read a bounded file from the caller's retained runtime workspace\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "in": "query", "name": "path", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": "string" }, "content_base64": { "type": "string" } }, "required": [ "path", "size", "sha256" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "writeAgentWorkspaceFile", "tags": [ "Agents" ], "description": "Write a bounded file in the caller's retained runtime workspace\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "content_base64": { "type": "string", "maxLength": 5592408, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "overwrite": { "default": false, "type": "boolean" } }, "required": [ "path", "content_base64" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": "string" }, "content_base64": { "type": "string" } }, "required": [ "path", "size", "sha256" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/{taskId}/workspace": { "delete": { "operationId": "deleteAgentWorkspace", "tags": [ "Agents" ], "description": "Permanently delete an owned idle workspace and its files; saved transcripts remain available\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "deleted" ] } }, "required": [ "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/runtime/preflight": { "get": { "operationId": "getAgentRuntimePreflight", "tags": [ "Agents" ], "description": "Report credentials and model compatibility the current user needs before this Agent can execute delegated work in its runtime\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "configured": { "type": "array", "items": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "credentialId": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "canConnect": { "type": "boolean" }, "adminOnly": { "type": "boolean" }, "reconnect": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "misconfigured": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "credentialId": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "canConnect": { "type": "boolean" }, "adminOnly": { "type": "boolean" }, "reconnect": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "incompatible": { "nullable": true, "type": "string" } }, "required": [ "ready", "configured", "missing", "misconfigured", "incompatible" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/runtime/claude-code/account": { "get": { "operationId": "getClaudeCodeAccount", "tags": [ "Agents" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "disconnected", "starting", "awaiting_code", "connecting", "connected", "failed", "expired" ] }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "flowId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "authorizationUrl": { "type": "string", "format": "uri" } }, "required": [ "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" }, "post": { "operationId": "startClaudeCodeSignIn", "tags": [ "Agents" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "disconnected", "starting", "awaiting_code", "connecting", "connected", "failed", "expired" ] }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "flowId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "authorizationUrl": { "type": "string", "format": "uri" } }, "required": [ "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" }, "delete": { "operationId": "disconnectClaudeCodeAccount", "tags": [ "Agents" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "disconnected", "starting", "awaiting_code", "connecting", "connected", "failed", "expired" ] }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "flowId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "authorizationUrl": { "type": "string", "format": "uri" } }, "required": [ "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/agents/{id}/runtime/claude-code/account/complete": { "post": { "operationId": "completeClaudeCodeSignIn", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flowId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "code": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "flowId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "disconnected", "starting", "awaiting_code", "connecting", "connected", "failed", "expired" ] }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "flowId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "authorizationUrl": { "type": "string", "format": "uri" } }, "required": [ "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/agents/{id}/runtime/claude-code/models": { "get": { "operationId": "getClaudeCodeModels", "tags": [ "Agents" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string", "maxLength": 2000 } }, "required": [ "value", "displayName", "description" ], "additionalProperties": false } } }, "required": [ "models" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/agents/{id}/runtime/credentials/{key}": { "put": { "operationId": "setAgentRuntimeCredential", "tags": [ "Agents" ], "description": "Store or replace one credential declared by an Agent's Agent Runtime configuration\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "value" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "enum": [ true ] } }, "required": [ "configured" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteAgentRuntimeCredential", "tags": [ "Agents" ], "description": "Remove one stored Agent Runtime credential value without changing its declaration\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{id}/runs": { "get": { "operationId": "getAgentRuns", "tags": [ "Agents" ], "description": "List Agent Runtime runs created by delegated tasks for this Agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "enum": [ "user", "team", "organization", "oauthClient", "serviceAccount", "system" ] }, "actorId": { "type": "string" }, "actorUserId": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workloadName": { "type": "string" }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "runtimeScope": { "type": "string" }, "runtimeLimits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false }, "attentionState": { "anyOf": [ { "type": "string", "enum": [ "input_required", "auth_required" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "virtualApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gatewayTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "nullable": true, "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "statusReason": { "nullable": true, "type": "string" }, "failure": { "nullable": true, "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 160 }, "retriable": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "code", "retriable", "message" ], "additionalProperties": false }, "stateChangedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hardDeadlineAt": { "type": "string", "format": "date-time" }, "lastModelActivityAt": { "nullable": true, "type": "string", "format": "date-time" }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "initiatorName": { "nullable": true, "type": "string" }, "workspace": { "nullable": true, "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "idle", "suspending", "suspended", "resuming", "deleting", "deleted" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "state", "expiresAt" ], "additionalProperties": false }, "canAttach": { "type": "boolean" }, "shareVisibility": { "anyOf": [ { "type": "string", "enum": [ "organization", "team", "user" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "shareTeamNames": { "nullable": true, "description": "Share recipient teams; null unless the viewer owns the run", "type": "array", "items": { "type": "string" } }, "shareUserNames": { "nullable": true, "description": "Share recipient users; null unless the viewer owns the run", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "taskId", "agentId", "actorKind", "actorId", "actorUserId", "title", "pinnedAt", "projectId", "workloadName", "backend", "runtimeScope", "runtimeLimits", "attentionState", "virtualApiKeyId", "gatewayTokenId", "startedAt", "endedAt", "state", "statusReason", "failure", "stateChangedAt", "hardDeadlineAt", "lastModelActivityAt", "sessionId", "initiatorName", "workspace", "shareVisibility", "shareTeamNames", "shareUserNames" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "startAgentRun", "tags": [ "Agents" ], "description": "Start a durable Agent Runtime session with this Agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 100000 }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attachments": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentBase64": { "type": "string", "minLength": 1 } }, "required": [ "name", "contentType", "contentBase64" ] } }, "limits": { "type": "object", "properties": { "tier": { "type": "string", "minLength": 1, "maxLength": 32 }, "minCpu": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 256 }, "minMemoryGib": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 256 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "type": "integer", "minimum": 1, "maximum": 100000 } } } }, "required": [ "message" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentName": { "type": "string" }, "prompt": { "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "limits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false } }, "required": [ "taskId", "state", "agentId", "agentName", "prompt", "projectId", "createdAt", "limits" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs": { "get": { "operationId": "getMyAgentRuns", "tags": [ "Agents" ], "description": "List Agent Runtime runs started by this user\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "pinned", "required": false }, { "schema": { "type": "string", "enum": [ "started", "recent", "pinned" ] }, "in": "query", "name": "sort", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "enum": [ "user", "team", "organization", "oauthClient", "serviceAccount", "system" ] }, "actorId": { "type": "string" }, "actorUserId": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workloadName": { "type": "string" }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "runtimeScope": { "type": "string" }, "runtimeLimits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false }, "attentionState": { "anyOf": [ { "type": "string", "enum": [ "input_required", "auth_required" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "virtualApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gatewayTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "nullable": true, "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "statusReason": { "nullable": true, "type": "string" }, "failure": { "nullable": true, "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 160 }, "retriable": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "code", "retriable", "message" ], "additionalProperties": false }, "stateChangedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hardDeadlineAt": { "type": "string", "format": "date-time" }, "lastModelActivityAt": { "nullable": true, "type": "string", "format": "date-time" }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmSessionId": { "type": "string", "description": "Key of the run's LLM logs (/llm/logs/:id): the session id its runtime sends" }, "prompt": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "icon": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "icon" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "terminalRetained": { "type": "boolean" } }, "required": [ "id", "organizationId", "taskId", "agentId", "actorKind", "actorId", "actorUserId", "title", "pinnedAt", "projectId", "workloadName", "backend", "runtimeScope", "runtimeLimits", "attentionState", "virtualApiKeyId", "gatewayTokenId", "startedAt", "endedAt", "state", "statusReason", "failure", "stateChangedAt", "hardDeadlineAt", "lastModelActivityAt", "sessionId", "llmSessionId", "prompt", "agent", "projectName", "projectIcon", "terminalRetained" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/{taskId}": { "get": { "operationId": "getMyAgentRun", "tags": [ "Agents" ], "description": "Get one Agent Runtime the user started or was granted access to\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "enum": [ "user", "team", "organization", "oauthClient", "serviceAccount", "system" ] }, "actorId": { "type": "string" }, "actorUserId": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workloadName": { "type": "string" }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "runtimeScope": { "type": "string" }, "runtimeLimits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false }, "attentionState": { "anyOf": [ { "type": "string", "enum": [ "input_required", "auth_required" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "virtualApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gatewayTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "nullable": true, "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "statusReason": { "nullable": true, "type": "string" }, "failure": { "nullable": true, "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 160 }, "retriable": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "code", "retriable", "message" ], "additionalProperties": false }, "stateChangedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hardDeadlineAt": { "type": "string", "format": "date-time" }, "lastModelActivityAt": { "nullable": true, "type": "string", "format": "date-time" }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmSessionId": { "type": "string", "description": "Key of the run's LLM logs (/llm/logs/:id): the session id its runtime sends" }, "prompt": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "icon": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "icon" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "terminalRetained": { "type": "boolean" }, "portForwardCommand": { "nullable": true, "type": "string" }, "workspace": { "nullable": true, "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "idle", "suspending", "suspended", "resuming", "deleting", "deleted" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "idleAt": { "nullable": true, "type": "string", "format": "date-time" }, "connection": { "nullable": true, "type": "object", "properties": { "hostname": { "type": "string" }, "shellCommand": { "type": "string" } }, "required": [ "hostname", "shellCommand" ], "additionalProperties": false } }, "required": [ "state", "expiresAt", "idleAt", "connection" ], "additionalProperties": false }, "viewerRole": { "type": "string", "enum": [ "owner", "shared" ] }, "canAttach": { "type": "boolean" }, "startupProgress": { "nullable": true, "type": "object", "properties": { "phase": { "type": "string", "enum": [ "queued", "scheduling", "pulling", "starting", "attaching" ] }, "message": { "type": "string" }, "detail": { "nullable": true, "type": "string" }, "resourceName": { "nullable": true, "type": "string" } }, "required": [ "phase", "message", "detail", "resourceName" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "taskId", "agentId", "actorKind", "actorId", "actorUserId", "title", "pinnedAt", "projectId", "workloadName", "backend", "runtimeScope", "runtimeLimits", "attentionState", "virtualApiKeyId", "gatewayTokenId", "startedAt", "endedAt", "state", "statusReason", "failure", "stateChangedAt", "hardDeadlineAt", "lastModelActivityAt", "sessionId", "llmSessionId", "prompt", "agent", "projectName", "projectIcon", "terminalRetained", "viewerRole" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateAgentRun", "tags": [ "Agents" ], "description": "Update one Agent Runtime started by this user\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "enum": [ "user", "team", "organization", "oauthClient", "serviceAccount", "system" ] }, "actorId": { "type": "string" }, "actorUserId": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workloadName": { "type": "string" }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "runtimeScope": { "type": "string" }, "runtimeLimits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false }, "attentionState": { "anyOf": [ { "type": "string", "enum": [ "input_required", "auth_required" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "virtualApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gatewayTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "nullable": true, "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "statusReason": { "nullable": true, "type": "string" }, "failure": { "nullable": true, "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 160 }, "retriable": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "code", "retriable", "message" ], "additionalProperties": false }, "stateChangedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hardDeadlineAt": { "type": "string", "format": "date-time" }, "lastModelActivityAt": { "nullable": true, "type": "string", "format": "date-time" }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmSessionId": { "type": "string", "description": "Key of the run's LLM logs (/llm/logs/:id): the session id its runtime sends" }, "prompt": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "icon": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "icon" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "taskId", "agentId", "actorKind", "actorId", "actorUserId", "title", "pinnedAt", "projectId", "workloadName", "backend", "runtimeScope", "runtimeLimits", "attentionState", "virtualApiKeyId", "gatewayTokenId", "startedAt", "endedAt", "state", "statusReason", "failure", "stateChangedAt", "hardDeadlineAt", "lastModelActivityAt", "sessionId", "llmSessionId", "prompt", "agent", "projectName", "projectIcon" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteAgentRun", "tags": [ "Agents" ], "description": "Delete one finished Agent Runtime session started by this user, with its saved files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/{taskId}/continue": { "post": { "operationId": "continueAgentRun", "tags": [ "Agents" ], "description": "Start a new Agent turn in an owned, retained workspace\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "default": "", "type": "string", "maxLength": 100000 }, "attachments": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentBase64": { "type": "string", "minLength": 1 } }, "required": [ "name", "contentType", "contentBase64" ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentName": { "type": "string" }, "prompt": { "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "limits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false } }, "required": [ "taskId", "state", "agentId", "agentName", "prompt", "projectId", "createdAt", "limits" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/{taskId}/cancel": { "post": { "operationId": "cancelAgentRun", "tags": [ "Agents" ], "description": "Cancel one active Agent Runtime session started by this user\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "TASK_STATE_CANCELED" ] } }, "required": [ "taskId", "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/bulk": { "delete": { "operationId": "bulkDeleteAgentRuns", "tags": [ "Agents" ], "description": "Delete several finished Agent Runtime sessions started by this user, with every turn and their saved files. A run that is still active, one whose saved files are still being suspended, or one this user did not start is reported in `failed` and leaves the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/bulk/workspace": { "delete": { "operationId": "bulkDeleteAgentWorkspaces", "tags": [ "Agents" ], "description": "Permanently delete the saved files of several finished Agent Runtime sessions started by this user; their transcripts remain available. A run with no saved files, one still running, or one this user did not start is reported in `failed` and leaves the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/bulk-cancel": { "post": { "operationId": "bulkCancelAgentRuns", "tags": [ "Agents" ], "description": "Cancel several active Agent Runtime sessions started by this user. A run that has already ended, or that this user did not start, is reported in `failed` and leaves the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runs/{taskId}/workspace/transfers": { "post": { "operationId": "startAgentWorkspaceTransfer", "tags": [ "Agents" ], "description": "Authorize a resumable transfer of one file to or from the caller's retained runtime workspace\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "download" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "direction", "path" ] }, { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "upload" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 1024 }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "location": { "type": "string", "enum": [ "workspace", "attachments" ] } }, "required": [ "direction", "path", "size", "sha256" ] } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "transferId": { "type": "string" }, "token": { "type": "string" }, "contentUrl": { "type": "string" }, "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": "string" }, "expiresInSeconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "transferId", "token", "contentUrl", "path", "size", "sha256", "expiresInSeconds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-workspace-transfers/{transferId}/content": { "get": { "operationId": "downloadAgentWorkspaceTransfer", "tags": [ "Agents" ], "description": "Stream the pinned contents of an authorized transfer; supports Range for resume\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "transferId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "uploadAgentWorkspaceTransfer", "tags": [ "Agents" ], "description": "Stream an authorized upload into the workspace and replace the destination atomically\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "transferId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sha256": { "type": "string" } }, "required": [ "path", "size", "sha256" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runtime-templates": { "get": { "operationId": "listAgentRuntimeTemplates", "tags": [ "Agents" ], "description": "List custom runtime choices without environment values or runtime configuration.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 }, "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "image": { "type": "string" } }, "required": [ "id", "name", "description", "icon", "hidden", "position", "image" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runtime-templates/built-ins": { "get": { "operationId": "listBuiltInAgentRuntimeSettings", "tags": [ "Agents" ], "description": "List the settings administrators chose for the maintained runtimes.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] } }, "required": [ "authentication" ], "additionalProperties": false } }, "additionalProperties": false }, "id": { "type": "string", "enum": [ "claude-code", "codex", "opencode", "hermes", "openclaw", "grok", "kimi", "copilot" ] } }, "required": [ "settings", "id" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runtime-templates/access": { "get": { "operationId": "listAgentRuntimeAccess", "tags": [ "Agents" ], "description": "List which Agent Runtimes the caller may put agents on and configure, and whether they may run an image that is none of them.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "runtimes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "canUse": { "type": "boolean" }, "canConfigure": { "type": "boolean" } }, "required": [ "id", "canUse", "canConfigure" ], "additionalProperties": false } }, "canConfigureAny": { "type": "boolean" } }, "required": [ "runtimes", "canConfigureAny" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-runtime-templates/{id}/apply-to-agents": { "get": { "operationId": "countAgentsBehindRuntime", "tags": [ "Organization" ], "description": "Count the existing agents of an Agent Runtime whose settings differ from the runtime's saved settings.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "claude-code", "codex", "opencode", "hermes", "openclaw", "grok", "kimi", "copilot" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "agents" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "post": { "operationId": "applyAgentRuntimeToAgents", "tags": [ "Organization" ], "description": "Give every existing agent of an Agent Runtime that runtime's current settings. Agents keep their own environment, credentials and ports.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "claude-code", "codex", "opencode", "hermes", "openclaw", "grok", "kimi", "copilot" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "updated" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/agent-runtime-templates/settings": { "get": { "operationId": "getRuntimeTemplateSettings", "tags": [ "Organization" ], "description": "Read editable runtime template settings.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "templates": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 }, "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "runtime": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^\\S+$" }, "command": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean", "enum": [ false ] }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string", "maxLength": 16384 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "maxCostUsd", "idleTimeoutMinutes" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "icon", "hidden", "position", "runtime" ], "additionalProperties": false } }, "builtIns": { "default": {}, "type": "object", "additionalProperties": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] } }, "required": [ "authentication" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "properties": { "claude-code": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "codex": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "opencode": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "hermes": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "openclaw": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "grok": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "kimi": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "copilot": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "custom-image": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "revision", "templates", "builtIns", "popularAgentOverrides" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "put": { "operationId": "saveRuntimeTemplateSettings", "tags": [ "Organization" ], "description": "Save custom templates, the maintained templates' settings, and the combined runtime order. Settings start new agents; apply them to existing agents separately. The revision prevents overwriting concurrent edits.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "templates": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 }, "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "runtime": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^\\S+$" }, "command": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean", "enum": [ false ] }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string", "maxLength": 16384 } }, "required": [ "key", "value" ] } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ] } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ] }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "maxCostUsd", "idleTimeoutMinutes" ] } }, "required": [ "id", "name", "description", "icon", "hidden", "position", "runtime" ] } }, "builtIns": { "default": {}, "type": "object", "additionalProperties": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] } }, "required": [ "authentication" ] } } } }, "required": [ "settings" ] } }, "popularAgentOverrides": { "nullable": true, "type": "object", "properties": { "claude-code": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "codex": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "opencode": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "hermes": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "openclaw": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "grok": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "kimi": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "copilot": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "custom-image": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "revision", "templates", "popularAgentOverrides" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "templates": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 }, "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "runtime": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^\\S+$" }, "command": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean", "enum": [ false ] }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string", "maxLength": 16384 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "maxCostUsd", "idleTimeoutMinutes" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "icon", "hidden", "position", "runtime" ], "additionalProperties": false } }, "builtIns": { "default": {}, "type": "object", "additionalProperties": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] } }, "required": [ "authentication" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "properties": { "claude-code": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "codex": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "opencode": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "hermes": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "openclaw": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "grok": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "kimi": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "copilot": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "custom-image": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "revision", "templates", "builtIns", "popularAgentOverrides" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/agent-runtime-templates/{id}": { "get": { "operationId": "getAgentRuntimeTemplate", "tags": [ "Agents" ], "description": "Read a template's starting configuration when creating or editing an agent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 }, "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "runtime": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^\\S+$" }, "command": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean", "enum": [ false ] }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "value": { "type": "string", "maxLength": 16384 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "maxCostUsd", "idleTimeoutMinutes" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "icon", "hidden", "position", "runtime" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-tools": { "get": { "operationId": "getAllAgentTools", "tags": [ "Agent Tools" ], "description": "Get all agent-tool relationships with pagination, sorting, and filtering\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "name", "agent", "origin", "createdAt" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "agentId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "origin", "required": false, "description": "A catalogId to filter by" }, { "schema": { "type": "string" }, "in": "query", "name": "mcpServerOwnerId", "required": false, "description": "Filter by MCP server owner user ID" }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeArchestraTools", "required": false, "description": "For test isolation" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "skipPagination", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeToolDetails", "required": false, "description": "Include each tool's description and parameter schema (default true). False returns null and {} for lightweight lists." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "tool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "catalogId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "createdAt", "updatedAt", "catalogId" ], "additionalProperties": false } }, "required": [ "id", "mcpServerId", "credentialResolutionMode", "createdAt", "updatedAt", "agent", "tool" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{agentId}/tools/{toolId}": { "post": { "operationId": "assignToolToAgent", "tags": [ "Agent Tools" ], "description": "Assign a tool to an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "resolveAtCallTime": { "type": "boolean" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "toolId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "unassignToolFromAgent", "tags": [ "Agent Tools" ], "description": "Unassign a tool from an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "toolId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/tools/bulk-assign": { "post": { "operationId": "bulkAssignTools", "tags": [ "Agent Tools" ], "description": "Assign multiple tools to multiple agents in bulk\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignments": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resolveAtCallTime": { "type": "boolean" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "toolId", "agentId" ] } } }, "required": [ "assignments" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "succeeded": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" } }, "required": [ "agentId", "toolId" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "agentId", "toolId", "error" ], "additionalProperties": false } }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" } }, "required": [ "agentId", "toolId" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed", "duplicates" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/tools/bulk-update": { "post": { "operationId": "bulkUpdateAgentTools", "tags": [ "Agent Tools" ], "description": "Apply a batch of tool assignments and removals across agents in one request. Intended for editors that save a whole tool selection at once: the batch produces a single config version per affected agent instead of one per tool. If the same agent/tool pair appears in both lists, the assignment wins and the removal is ignored. A pair repeated within a list is written once but reported once per occurrence. Agents the caller cannot modify are reported two different ways: an agent that belongs to another organization or no longer exists is reported per entry in `failed`, and the rest of the batch still applies; an agent in the caller's own organization whose agent type the caller lacks `update` on rejects the entire request with 403 and applies nothing.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignments": { "default": [], "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resolveAtCallTime": { "type": "boolean" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "toolId", "agentId" ] } }, "removals": { "default": [], "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "agentId", "toolId" ] } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "succeeded": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" } }, "required": [ "agentId", "toolId" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "agentId", "toolId", "error" ], "additionalProperties": false } }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" } }, "required": [ "agentId", "toolId" ], "additionalProperties": false } }, "removed": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" } }, "required": [ "agentId", "toolId" ], "additionalProperties": false } }, "notAssigned": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "toolId": { "type": "string" } }, "required": [ "agentId", "toolId" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed", "duplicates", "removed", "notAssigned" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{agentId}/tools": { "get": { "operationId": "getAgentTools", "tags": [ "Agent Tools" ], "description": "Get all tools for an agent (both proxy-sniffed and MCP tools)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "catalogId", "required": false, "description": "Only return tools from this catalog item, e.g. to check whether one server's tools are assigned without loading every tool's schema" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "description": { "nullable": true, "type": "string" }, "meta": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "clonedPendingDiscovery": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description", "meta", "clonedPendingDiscovery", "createdAt", "updatedAt", "deletedAt", "mcpServerId", "credentialResolutionMode" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-tools/{id}": { "patch": { "operationId": "updateAgentTool", "tags": [ "Agent Tools" ], "description": "Update an agent-tool relationship\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "credentialResolutionMode" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{agentId}/delegations": { "get": { "operationId": "getAgentDelegations", "tags": [ "Agent Delegations" ], "description": "Get all delegation targets for an agent. Not applicable to LLM proxies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "systemPrompt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "syncAgentDelegations", "tags": [ "Agent Delegations" ], "description": "Sync delegation targets for an agent. Replaces all existing delegations with the new list. Not applicable to LLM proxies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetAgentIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "targetAgentIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } }, "required": [ "added", "removed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agents/{agentId}/delegations/{targetAgentId}": { "post": { "operationId": "createAgentDelegation", "tags": [ "Agent Delegations" ], "description": "Create one delegation edge without replacing other targets; repeated creation reports created=false.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "targetAgentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "boolean" } }, "required": [ "created" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteAgentDelegation", "tags": [ "Agent Delegations" ], "description": "Remove a specific delegation from an agent. Not applicable to LLM proxies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "targetAgentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-delegations": { "get": { "operationId": "getAllDelegationConnections", "tags": [ "Agent Delegations" ], "description": "Get all agent delegation connections for canvas visualization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "sourceAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceAgentName": { "type": "string" }, "targetAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "targetAgentName": { "type": "string" }, "toolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "sourceAgentId", "sourceAgentName", "targetAgentId", "targetAgentName", "toolId" ], "additionalProperties": false } }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } } }, "required": [ "connections", "agents" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/anthropic/v1/messages": { "post": { "operationId": "anthropicMessagesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Send a message to Anthropic using the default agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-beta", "required": false, "description": "Beta features to enable (comma-separated)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header (Bearer token for OAuth)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/anthropic/{agentId}/v1/messages": { "post": { "operationId": "anthropicMessagesWithAgent", "tags": [ "LLM Proxy" ], "description": "Send a message to Anthropic using a specific agent (n8n URL format)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-beta", "required": false, "description": "Beta features to enable (comma-separated)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header (Bearer token for OAuth)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/anthropic/v1/models": { "get": { "operationId": "anthropicListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List Anthropic models (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "model" ] }, "id": { "type": "string" }, "display_name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "type", "id", "display_name" ], "additionalProperties": false } }, "has_more": { "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/anthropic/{agentId}/v1/models": { "get": { "operationId": "anthropicListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List Anthropic models (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "model" ] }, "id": { "type": "string" }, "display_name": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "type", "id", "display_name" ], "additionalProperties": false } }, "has_more": { "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/api-keys": { "get": { "operationId": "getApiKeys", "tags": [ "API Keys" ], "description": "List the authenticated user's Archestra API keys\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`apiKey:read`](/docs/reference/permissions#apiKey:read): View API keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "start": { "nullable": true, "type": "string" }, "prefix": { "nullable": true, "type": "string" }, "userId": { "type": "string" }, "enabled": { "nullable": true, "type": "boolean" }, "lastRequest": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": {} }, "permissions": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "id", "name", "start", "prefix", "userId", "enabled", "lastRequest", "expiresAt", "createdAt", "updatedAt", "metadata", "permissions" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "apiKey:read" ] } }, "post": { "operationId": "createApiKey", "tags": [ "API Keys" ], "description": "Create an Archestra API key for the authenticated user\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`apiKey:create`](/docs/reference/permissions#apiKey:create): Create API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "nullable": true, "type": "string", "maxLength": 32 }, "expiresIn": { "nullable": true, "type": "integer", "minimum": 86400, "maximum": 31536000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "start": { "nullable": true, "type": "string" }, "prefix": { "nullable": true, "type": "string" }, "userId": { "type": "string" }, "enabled": { "nullable": true, "type": "boolean" }, "lastRequest": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": {} }, "permissions": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "key": { "type": "string" } }, "required": [ "id", "name", "start", "prefix", "userId", "enabled", "lastRequest", "expiresAt", "createdAt", "updatedAt", "metadata", "permissions", "key" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "apiKey:create" ] } } }, "/api/api-keys/{id}": { "get": { "operationId": "getApiKey", "tags": [ "API Keys" ], "description": "Get one authenticated user's Archestra API key\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`apiKey:read`](/docs/reference/permissions#apiKey:read): View API keys", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "start": { "nullable": true, "type": "string" }, "prefix": { "nullable": true, "type": "string" }, "userId": { "type": "string" }, "enabled": { "nullable": true, "type": "boolean" }, "lastRequest": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": {} }, "permissions": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "id", "name", "start", "prefix", "userId", "enabled", "lastRequest", "expiresAt", "createdAt", "updatedAt", "metadata", "permissions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "apiKey:read" ] } }, "delete": { "operationId": "deleteApiKey", "tags": [ "API Keys" ], "description": "Delete an Archestra API key for the authenticated user\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`apiKey:delete`](/docs/reference/permissions#apiKey:delete): Delete API keys", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "apiKey:delete" ] } } }, "/api/api-keys/bulk": { "delete": { "operationId": "bulkDeleteApiKeys", "tags": [ "API Keys" ], "description": "Delete several of the authenticated user's Archestra API keys in one request. Keys are personal, so an id belonging to anyone else is reported in `failed` as not found and the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`apiKey:delete`](/docs/reference/permissions#apiKey:delete): Delete API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "apiKey:delete" ] } } }, "/api/apps/{id}/transfer-ownership": { "post": { "operationId": "transferAppOwnership", "tags": [ "Ownership" ], "description": "Transfer ownership to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps": { "get": { "operationId": "getApps", "tags": [ "Apps" ], "description": "List apps visible to the caller (paginated).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "authorIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "excludeAuthorIds", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "type": "boolean" }, "in": "query", "name": "pinned", "required": false, "description": "Only return apps the current user has pinned." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "executionModel": { "type": "string", "enum": [ "viewer-scoped", "server-scoped" ] }, "cspOrigin": { "type": "string", "enum": [ "platform-pinned", "author-declared" ] }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "icon": { "nullable": true, "type": "string" }, "iconUrl": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "owned" ] }, "id": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "latestVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" }, "locked": { "type": "boolean" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "name", "description", "executionModel", "cspOrigin", "pinnedAt", "labels", "icon", "iconUrl", "createdBy", "source", "id", "slug", "scope", "authorId", "authorName", "viewerRole", "latestVersion", "enabled", "locked", "teams", "users" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "executionModel": { "type": "string", "enum": [ "viewer-scoped", "server-scoped" ] }, "cspOrigin": { "type": "string", "enum": [ "platform-pinned", "author-declared" ] }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "icon": { "nullable": true, "type": "string" }, "iconUrl": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "external" ] }, "catalogId": { "type": "string" }, "mcpServerId": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "resourceUri": { "type": "string" }, "toolName": { "type": "string" }, "requiresInput": { "type": "boolean" } }, "required": [ "name", "description", "executionModel", "cspOrigin", "pinnedAt", "labels", "icon", "iconUrl", "createdBy", "source", "catalogId", "mcpServerId", "scope", "resourceUri", "toolName", "requiresInput" ], "additionalProperties": false } ] } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createApp", "tags": [ "Apps" ], "description": "Create a new MCP App.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:create`](/docs/reference/permissions#app:create): Create new MCP Apps", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 500 }, "html": { "type": "string", "minLength": 1 }, "uiPermissions": { "type": "object", "properties": { "camera": { "type": "object", "properties": {} }, "microphone": { "type": "object", "properties": {} }, "geolocation": { "type": "object", "properties": {} }, "clipboardWrite": { "type": "object", "properties": {} } }, "additionalProperties": false }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string", "maxLength": 1048576 }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "openInChat": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string" } }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:create" ] } } }, "/api/apps/external/{catalogId}": { "get": { "operationId": "getExternalApp", "tags": [ "Apps" ], "description": "Resolve an external UI-providing app by catalog id: its UI resource and the caller's accessible installs (for the standalone run page's install selector).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "resourceUri": { "type": "string" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "resourceUri": { "type": "string" }, "toolName": { "type": "string" }, "name": { "type": "string" }, "requiresInput": { "type": "boolean" } }, "required": [ "resourceUri", "toolName", "name", "requiresInput" ], "additionalProperties": false } }, "defaultMcpServerId": { "nullable": true, "type": "string" }, "installs": { "type": "array", "items": { "type": "object", "properties": { "mcpServerId": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "localInstallationStatus": { "nullable": true, "type": "string" } }, "required": [ "mcpServerId", "scope", "ownerId", "teamId", "name", "localInstallationStatus" ], "additionalProperties": false } } }, "required": [ "catalogId", "name", "description", "resourceUri", "resources", "defaultMcpServerId", "installs" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } } }, "/api/apps/external/{catalogId}/icon": { "get": { "operationId": "getExternalAppIcon", "tags": [ "Apps" ], "description": "The image icon of an external app's backing server, for the apps list, which links image icons instead of carrying them inline.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "v", "required": false, "description": "Content version; any value." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } } }, "/api/apps/{appId}/icon": { "get": { "operationId": "getAppIcon", "tags": [ "Apps" ], "description": "The image icon of an app the caller may view, for the apps list, which links image icons instead of carrying them inline.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "v", "required": false, "description": "Content version; any value." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/labels/keys": { "get": { "operationId": "getAppLabelKeys", "tags": [ "Apps" ], "description": "Get all label keys used by apps\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } } }, "/api/apps/labels/values": { "get": { "operationId": "getAppLabelValues", "tags": [ "Apps" ], "description": "Get all label values used by apps\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } } }, "/api/app-templates": { "get": { "operationId": "getAppTemplates", "tags": [ "Apps" ], "description": "List the curated starter templates a new app can use.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "html": { "type": "string" } }, "required": [ "id", "name", "description", "html" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } } }, "/api/apps/{appId}/open-in-chat": { "post": { "operationId": "openAppInChat", "tags": [ "Apps" ], "description": "Open an existing app in chat: create a conversation with the app already rendered (no model turn) and return its id to navigate to.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:create`](/docs/reference/permissions#chat:create): Start new chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "conversationId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:create" ] } } }, "/api/apps/external/{mcpServerId}/open-in-chat": { "post": { "operationId": "openExternalAppInChat", "tags": [ "Apps" ], "description": "Open an external (MCP-server) UI app in chat: create a conversation and return its id to navigate to. When the tool needs no inputs the app is seeded already rendered (no model turn); when it has required inputs the conversation is created empty and the response carries an opening prompt for the client to send.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps\n[`chat:create`](/docs/reference/permissions#chat:create): Start new chat conversations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceUri": { "type": "string", "minLength": 1 } }, "required": [ "resourceUri" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "mcpServerId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mode": { "type": "string", "enum": [ "render", "prompt" ] }, "prompt": { "type": "string" } }, "required": [ "conversationId", "mode" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read", "chat:create" ] } } }, "/api/apps/{appId}/pin": { "put": { "operationId": "pinApp", "tags": [ "Apps" ], "description": "Pin an app for the current user (mirrors project pins). Personal — does not affect other members. Any user who can view the app may pin it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "unpinApp", "tags": [ "Apps" ], "description": "Remove the current user's pin on an app. Idempotent; intentionally no visibility check, so a stale pin on an app that was since re-scoped away (or deleted) can still be cleared.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/external/{mcpServerId}/pin": { "put": { "operationId": "pinExternalApp", "tags": [ "Apps" ], "description": "Pin an external (MCP-server) UI app for the current user, identified by install + resource + tool (several tools of one server can share a UI resource, so the tool name pins one tile, not the group). Personal — does not affect other members.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceUri": { "type": "string", "minLength": 1 }, "toolName": { "type": "string", "minLength": 1 } }, "required": [ "resourceUri", "toolName" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "mcpServerId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } }, "delete": { "operationId": "unpinExternalApp", "tags": [ "Apps" ], "description": "Remove the current user's pin on an external app. Idempotent; intentionally no access check, so a stale pin on an install the user lost access to can still be cleared. `resourceUri` and `toolName` ride the query string (DELETE carries no body).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "resourceUri", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "toolName", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "mcpServerId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read" ] } } }, "/api/apps/{appId}": { "get": { "operationId": "getApp", "tags": [ "Apps" ], "description": "Get a single app by id or slug, if the caller may view it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "authorName": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels", "createdBy", "teams", "users", "viewerRole", "authorName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateApp", "tags": [ "Apps" ], "description": "Update an app's metadata and/or html (forks a new version).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "baseVersion": { "description": "Expected current content version. A stale value rejects the entire update with 409 before any changes persist.", "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "nullable": true, "type": "string", "maxLength": 500 }, "html": { "type": "string", "minLength": 1 }, "uiPermissions": { "type": "object", "properties": { "camera": { "type": "object", "properties": {} }, "microphone": { "type": "object", "properties": {} }, "geolocation": { "type": "object", "properties": {} }, "clipboardWrite": { "type": "object", "properties": {} } }, "additionalProperties": false }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string", "maxLength": 1048576 }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "openInFullscreen": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteApp", "tags": [ "Apps" ], "description": "Soft-delete an app the caller owns or administers.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/bulk": { "delete": { "operationId": "bulkDeleteApps", "tags": [ "Apps" ], "description": "Soft-delete several apps in one request. Each id is authorized exactly as the single-app delete authorizes its own, so an app the caller cannot see or administer — and a locked app, which is never deletable until unlocked — is reported in `failed` while the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/enable": { "post": { "operationId": "enableApp", "tags": [ "Apps" ], "description": "Enable a disabled app, making it live at its scope.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "authorName": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels", "createdBy", "teams", "users", "viewerRole", "authorName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/disable": { "post": { "operationId": "disableApp", "tags": [ "Apps" ], "description": "Disable an app, pulling it back to an author-only state.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "authorName": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels", "createdBy", "teams", "users", "viewerRole", "authorName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/lock": { "post": { "operationId": "lockApp", "tags": [ "Apps" ], "description": "Lock an app, refusing all chat-driven modification (and REST html replacement/deletion) until unlocked.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "authorName": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels", "createdBy", "teams", "users", "viewerRole", "authorName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/unlock": { "post": { "operationId": "unlockApp", "tags": [ "Apps" ], "description": "Unlock a locked app, making it editable again.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "authorName": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels", "createdBy", "teams", "users", "viewerRole", "authorName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/versions": { "get": { "operationId": "getAppVersions", "tags": [ "Apps" ], "description": "List an app's versions, newest first.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "html": { "type": "string" }, "uiPermissions": { "nullable": true, "type": "object", "properties": { "camera": { "type": "object", "properties": {}, "additionalProperties": false }, "microphone": { "type": "object", "properties": {}, "additionalProperties": false }, "geolocation": { "type": "object", "properties": {}, "additionalProperties": false }, "clipboardWrite": { "type": "object", "properties": {}, "additionalProperties": false } }, "additionalProperties": false }, "contentHash": { "type": "string" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "version", "html", "uiPermissions", "contentHash", "spec", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/versions/summaries": { "get": { "operationId": "getAppVersionSummaries", "tags": [ "Apps" ], "description": "List an app's version metadata without returning the HTML artifacts.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "version", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/versions/{version}": { "get": { "operationId": "getAppVersion", "tags": [ "Apps" ], "description": "Get a specific app version.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "html": { "type": "string" }, "uiPermissions": { "nullable": true, "type": "object", "properties": { "camera": { "type": "object", "properties": {}, "additionalProperties": false }, "microphone": { "type": "object", "properties": {}, "additionalProperties": false }, "geolocation": { "type": "object", "properties": {}, "additionalProperties": false }, "clipboardWrite": { "type": "object", "properties": {}, "additionalProperties": false } }, "additionalProperties": false }, "contentHash": { "type": "string" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "version", "html", "uiPermissions", "contentHash", "spec", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/versions/{version}/restore": { "post": { "operationId": "restoreAppVersion", "tags": [ "Apps" ], "description": "Restore an immutable app version by copying its artifact forward as a new head version. History is never rewritten.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "baseVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "baseVersion" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "templateId": { "nullable": true, "type": "string" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spec": { "nullable": true, "type": "object", "properties": { "summary": { "type": "string", "description": "One-line summary of what the app is for." }, "features": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities the app should provide." }, "data": { "description": "What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "ui": { "description": "UI / style direction as a free-form prose string, not a structured object.", "nullable": true, "type": "string" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "Full names of the MCP tools the app calls through window.archestra." } }, "required": [ "summary", "features", "tools" ], "additionalProperties": false }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "openInFullscreen": { "type": "boolean" }, "locked": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "icon": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "authorId", "name", "slug", "description", "templateId", "mcpServerId", "spec", "latestVersion", "enabled", "openInFullscreen", "locked", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "scope", "environmentId", "icon", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/tools": { "get": { "operationId": "getAppTools", "tags": [ "Apps" ], "description": "List the tools assigned to an app, including each assignment's stored server pin and credential resolution mode.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "description": { "nullable": true, "type": "string" }, "meta": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "clonedPendingDiscovery": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description", "meta", "clonedPendingDiscovery", "createdAt", "updatedAt", "deletedAt", "mcpServerId", "credentialResolutionMode" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/diagnostics": { "post": { "operationId": "postAppRenderDiagnostics", "tags": [ "Apps" ], "description": "Record the calling user's latest render diagnostics for an app. An empty entries array means the render was clean.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "entries": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 32 }, "message": { "type": "string", "maxLength": 1000 } }, "required": [ "type", "message" ] } } }, "required": [ "version", "entries" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/screenshot": { "post": { "operationId": "postAppRenderScreenshot", "tags": [ "Apps" ], "description": "Record the calling user's latest render screenshot for an app (a base64 image data URL the app self-captured).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "dataUrl": { "type": "string", "maxLength": 2000000, "pattern": "^data:image\\/(png|jpeg|webp);base64," } }, "required": [ "version", "dataUrl" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/apps/{appId}/tools/{toolId}": { "post": { "operationId": "assignToolToApp", "tags": [ "Apps" ], "description": "Assign an upstream tool to an app.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "toolId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "unassignToolFromApp", "tags": [ "Apps" ], "description": "Unassign a tool from an app.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "toolId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/archestra-cli/{target}": { "get": { "operationId": "downloadArchestraCli", "tags": [ "Archestra CLI" ], "description": "Download the archestra program for one operating system and CPU, for example darwin-arm64, linux-x86_64 or windows-AMD64.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "pattern": "^(darwin|linux|windows)-(arm64|aarch64|x86_64|amd64)$" }, "in": "path", "name": "target", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/archestra/chat/completions": { "post": { "operationId": "archestraChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Archestra (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchestraChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchestraChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/archestra/{agentId}/chat/completions": { "post": { "operationId": "archestraChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Archestra for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchestraChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchestraChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/audit-logs": { "get": { "operationId": "getAuditLogs", "tags": [ "Audit Log" ], "description": "Get paginated audit log events for the organization. Requires auditLog:read permission (Admin only by default).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`auditLog:read`](/docs/reference/permissions#auditLog:read): View audit log records of your own administrative actions", "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Filter events on or after this date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Filter events on or before this date (ISO 8601)" }, { "schema": { "type": "string" }, "in": "query", "name": "actorId", "required": false, "description": "Filter by actor ID" }, { "schema": { "type": "string", "enum": [ "resourcePermissions.updated", "hook.created", "hook.updated", "hook.deleted", "agent.created", "agent.updated", "agent.deleted", "agent.restored", "agent.imported", "agent.purged", "agent.bulk_deleted", "agentRun.created", "agentRun.canceled", "agentRun.updated", "agentRun.deleted", "agentRun.bulk_canceled", "agentRun.bulk_deleted", "agentRun.bulk_files_deleted", "agentRun.reviewDecided", "agentRun.terminal_attached", "agentRun.terminal_detached", "agentRun.terminal_interrupted", "blobProvider.created", "blobProvider.updated", "blobProvider.deleted", "blobProvider.tested", "browserStorageState.deleted", "costExport.created", "costExport.updated", "costExport.deleted", "costExport.run", "credential.created", "credential.updated", "credential.deleted", "agentTool.created", "agentTool.updated", "agentTool.deleted", "agentTool.bulk_assigned", "agentTool.bulk_removed", "agentTool.bulk_updated", "apiKey.created", "apiKey.deleted", "apiKey.bulk_deleted", "app.created", "app.updated", "app.deleted", "app.bulk_deleted", "chatOpsBinding.created", "chatOpsBinding.updated", "chatOpsBinding.deleted", "chatOpsBinding.refreshed", "chatOpsConfig.updated", "plugin.created", "plugin.updated", "plugin.deleted", "plugin.syncTriggered", "clientConnection.updated", "clientPrivacy.updated", "connectedClient.disconnected", "desktopDeviceSignIn.updated", "desktopDevice.updated", "desktopDevice.deleted", "connector.created", "connector.updated", "connector.deleted", "connector.restored", "connector.purged", "connector.bulk_updated", "connector.bulk_deleted", "connector.permission_sync_triggered", "connector.synced", "defaultUserLimit.created", "defaultUserLimit.updated", "defaultUserLimit.deleted", "environment.created", "environment.updated", "environment.deleted", "environment.bulk_deleted", "identityProvider.created", "identityProvider.updated", "identityProvider.deleted", "internalMcpCatalog.created", "internalMcpCatalog.updated", "internalMcpCatalog.deleted", "internalMcpCatalog.restored", "internalMcpCatalog.reinstalled", "invitation.created", "invitation.deleted", "knowledgeBase.created", "knowledgeBase.updated", "knowledgeBase.deleted", "knowledgeBase.restored", "knowledgeBase.purged", "knowledgeBase.bulk_deleted", "knowledgeDirectory.created", "knowledgeDirectory.updated", "knowledgeDirectory.deleted", "knowledgeDirectory.bulk_deleted", "knowledgeFile.created", "knowledgeFile.updated", "knowledgeFile.content_upserted", "knowledgeFile.deleted", "knowledgeFile.bulk_deleted", "limit.created", "limit.updated", "limit.reset", "limit.deleted", "limit.bulk_deleted", "llmModel.updated", "llmModel.deleted", "llmModel.synced", "llmModel.bulk_updated", "llmModel.cost_backfill_started", "modelPool.created", "modelPool.updated", "modelPool.deleted", "autoRouter.created", "autoRouter.updated", "autoRouter.deleted", "oauthClient.created", "oauthClient.updated", "oauthClient.deleted", "oauthClient.rotated", "oauthClient.bulk_deleted", "oauthClient.token_exchanged", "oauthClientFederatedCredential.created", "oauthClientFederatedCredential.updated", "oauthClientFederatedCredential.deleted", "llmProviderApiKey.created", "llmProviderApiKey.updated", "llmProviderApiKey.deleted", "llmProxy.updated", "llmProviderApiKey.bulk_deleted", "mcpServer.created", "mcpServer.updated", "mcpServer.deleted", "mcpServer.restored", "mcpServer.reinstalled", "mcpServer.hardReset", "mcpServer.bulk_deleted", "member.bulk_deleted", "member.created", "member.role_updated", "member.deleted", "organization.updated", "project.created", "project.updated", "project.deleted", "project.restored", "project.purged", "project.bulk_deleted", "role.created", "role.updated", "role.deleted", "role.bulk_deleted", "scheduleTrigger.created", "scheduleTrigger.updated", "scheduleTrigger.deleted", "scheduleTrigger.triggered", "serviceAccount.created", "serviceAccount.updated", "serviceAccount.deleted", "serviceAccount.bulk_deleted", "serviceAccount.bulk_updated", "serviceAccount.token_exchanged", "serviceAccountFederatedCredential.created", "serviceAccountFederatedCredential.updated", "serviceAccountFederatedCredential.deleted", "skill.created", "skill.updated", "skill.deleted", "skill.bulk_deleted", "skill.restored", "skill.purged", "skill.imported", "skillShareLink.created", "skillShareLink.rotated", "skillShareLink.revoked", "team.created", "team.updated", "team.deleted", "team.bulk_deleted", "guardrailsPolicy.updated", "openappaYell.updated", "openappaBatteryInstall.created", "openappaBatteryInstall.updated", "openappaBatteryInstall.deleted", "openappaBatteryPackage.updated", "openappaBatteryPackage.deleted", "openappaCredentialBinding.updated", "user.password_reset", "userToken.rotated", "userLimitUsage.reset", "virtualApiKey.created", "virtualApiKey.updated", "virtualApiKey.deleted", "virtualApiKey.bulk_deleted", "auth.impersonation_started", "auth.impersonation_stopped", "auth.signed_in", "auth.signed_out", "auth.signed_up", "auth.sso_callback", "auth.sessions_revoked", "unknown.created", "unknown.updated", "unknown.deleted" ] }, "in": "query", "name": "action", "required": false, "description": "Filter by action type (dotted name, e.g. agent.created)" }, { "schema": { "type": "string", "enum": [ "success", "failure", "denied" ] }, "in": "query", "name": "outcome", "required": false, "description": "Filter by outcome (success, failure, or denied)" }, { "schema": { "type": "string", "enum": [ "user", "api_key", "service_account", "system", "sso" ] }, "in": "query", "name": "actorType", "required": false, "description": "Filter by actor type (user, api_key, sso, or system)" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceType", "required": false, "description": "Filter by resource type (e.g. agent, role); a comma-separated list matches any of them" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceId", "required": false, "description": "Filter by resource ID (e.g. a specific agent's ID)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eventSequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "organizationId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actorId": { "nullable": true, "type": "string" }, "actorType": { "type": "string", "enum": [ "user", "api_key", "service_account", "system", "sso" ] }, "actorName": { "nullable": true, "type": "string" }, "actorEmail": { "nullable": true, "type": "string" }, "impersonatedBy": { "nullable": true, "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "resourcePermissions.updated", "hook.created", "hook.updated", "hook.deleted", "agent.created", "agent.updated", "agent.deleted", "agent.restored", "agent.imported", "agent.purged", "agent.bulk_deleted", "agentRun.created", "agentRun.canceled", "agentRun.updated", "agentRun.deleted", "agentRun.bulk_canceled", "agentRun.bulk_deleted", "agentRun.bulk_files_deleted", "agentRun.reviewDecided", "agentRun.terminal_attached", "agentRun.terminal_detached", "agentRun.terminal_interrupted", "blobProvider.created", "blobProvider.updated", "blobProvider.deleted", "blobProvider.tested", "browserStorageState.deleted", "costExport.created", "costExport.updated", "costExport.deleted", "costExport.run", "credential.created", "credential.updated", "credential.deleted", "agentTool.created", "agentTool.updated", "agentTool.deleted", "agentTool.bulk_assigned", "agentTool.bulk_removed", "agentTool.bulk_updated", "apiKey.created", "apiKey.deleted", "apiKey.bulk_deleted", "app.created", "app.updated", "app.deleted", "app.bulk_deleted", "chatOpsBinding.created", "chatOpsBinding.updated", "chatOpsBinding.deleted", "chatOpsBinding.refreshed", "chatOpsConfig.updated", "plugin.created", "plugin.updated", "plugin.deleted", "plugin.syncTriggered", "clientConnection.updated", "clientPrivacy.updated", "connectedClient.disconnected", "desktopDeviceSignIn.updated", "desktopDevice.updated", "desktopDevice.deleted", "connector.created", "connector.updated", "connector.deleted", "connector.restored", "connector.purged", "connector.bulk_updated", "connector.bulk_deleted", "connector.permission_sync_triggered", "connector.synced", "defaultUserLimit.created", "defaultUserLimit.updated", "defaultUserLimit.deleted", "environment.created", "environment.updated", "environment.deleted", "environment.bulk_deleted", "identityProvider.created", "identityProvider.updated", "identityProvider.deleted", "internalMcpCatalog.created", "internalMcpCatalog.updated", "internalMcpCatalog.deleted", "internalMcpCatalog.restored", "internalMcpCatalog.reinstalled", "invitation.created", "invitation.deleted", "knowledgeBase.created", "knowledgeBase.updated", "knowledgeBase.deleted", "knowledgeBase.restored", "knowledgeBase.purged", "knowledgeBase.bulk_deleted", "knowledgeDirectory.created", "knowledgeDirectory.updated", "knowledgeDirectory.deleted", "knowledgeDirectory.bulk_deleted", "knowledgeFile.created", "knowledgeFile.updated", "knowledgeFile.content_upserted", "knowledgeFile.deleted", "knowledgeFile.bulk_deleted", "limit.created", "limit.updated", "limit.reset", "limit.deleted", "limit.bulk_deleted", "llmModel.updated", "llmModel.deleted", "llmModel.synced", "llmModel.bulk_updated", "llmModel.cost_backfill_started", "modelPool.created", "modelPool.updated", "modelPool.deleted", "autoRouter.created", "autoRouter.updated", "autoRouter.deleted", "oauthClient.created", "oauthClient.updated", "oauthClient.deleted", "oauthClient.rotated", "oauthClient.bulk_deleted", "oauthClient.token_exchanged", "oauthClientFederatedCredential.created", "oauthClientFederatedCredential.updated", "oauthClientFederatedCredential.deleted", "llmProviderApiKey.created", "llmProviderApiKey.updated", "llmProviderApiKey.deleted", "llmProxy.updated", "llmProviderApiKey.bulk_deleted", "mcpServer.created", "mcpServer.updated", "mcpServer.deleted", "mcpServer.restored", "mcpServer.reinstalled", "mcpServer.hardReset", "mcpServer.bulk_deleted", "member.bulk_deleted", "member.created", "member.role_updated", "member.deleted", "organization.updated", "project.created", "project.updated", "project.deleted", "project.restored", "project.purged", "project.bulk_deleted", "role.created", "role.updated", "role.deleted", "role.bulk_deleted", "scheduleTrigger.created", "scheduleTrigger.updated", "scheduleTrigger.deleted", "scheduleTrigger.triggered", "serviceAccount.created", "serviceAccount.updated", "serviceAccount.deleted", "serviceAccount.bulk_deleted", "serviceAccount.bulk_updated", "serviceAccount.token_exchanged", "serviceAccountFederatedCredential.created", "serviceAccountFederatedCredential.updated", "serviceAccountFederatedCredential.deleted", "skill.created", "skill.updated", "skill.deleted", "skill.bulk_deleted", "skill.restored", "skill.purged", "skill.imported", "skillShareLink.created", "skillShareLink.rotated", "skillShareLink.revoked", "team.created", "team.updated", "team.deleted", "team.bulk_deleted", "guardrailsPolicy.updated", "openappaYell.updated", "openappaBatteryInstall.created", "openappaBatteryInstall.updated", "openappaBatteryInstall.deleted", "openappaBatteryPackage.updated", "openappaBatteryPackage.deleted", "openappaCredentialBinding.updated", "user.password_reset", "userToken.rotated", "userLimitUsage.reset", "virtualApiKey.created", "virtualApiKey.updated", "virtualApiKey.deleted", "virtualApiKey.bulk_deleted", "auth.impersonation_started", "auth.impersonation_stopped", "auth.signed_in", "auth.signed_out", "auth.signed_up", "auth.sso_callback", "auth.sessions_revoked", "unknown.created", "unknown.updated", "unknown.deleted" ] }, { "type": "string" } ] }, "outcome": { "type": "string", "enum": [ "success", "failure", "denied" ] }, "resourceType": { "nullable": true, "type": "string" }, "resourceId": { "nullable": true, "type": "string" }, "resourceName": { "nullable": true, "type": "string" }, "before": { "nullable": true, "type": "object", "additionalProperties": {} }, "after": { "nullable": true, "type": "object", "additionalProperties": {} }, "httpMethod": { "nullable": true, "type": "string" }, "httpPath": { "nullable": true, "type": "string" }, "httpRoute": { "nullable": true, "type": "string" }, "httpStatus": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "requestId": { "nullable": true, "type": "string" }, "sourceIp": { "nullable": true, "type": "string" }, "userAgent": { "nullable": true, "type": "string" }, "impersonatedByEmail": { "nullable": true, "type": "string" } }, "required": [ "id", "eventSequence", "organizationId", "occurredAt", "createdAt", "actorId", "actorType", "actorName", "actorEmail", "impersonatedBy", "action", "outcome", "resourceType", "resourceId", "resourceName", "before", "after", "httpMethod", "httpPath", "httpRoute", "httpStatus", "requestId", "sourceIp", "userAgent", "impersonatedByEmail" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "auditLog:read" ] } } }, "/api/audit-logs/resources": { "get": { "operationId": "getAuditLogResources", "tags": [ "Audit Log" ], "description": "Get the resources that have audit events, for the log's resource filter. Covers agents, apps, environments, MCP servers, roles, skills and teams. Each resource has the name from its latest named event. Requires auditLog:read. Without auditLog:admin, only resources from the caller's own events are listed.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`auditLog:read`](/docs/reference/permissions#auditLog:read): View audit log records of your own administrative actions", "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false, "description": "Case-insensitive substring of the resource name" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceId", "required": false, "description": "Return only this resource, e.g. to label a preselected filter" }, { "schema": { "type": "string" }, "in": "query", "name": "resourceType", "required": false, "description": "Offer only resources of these types (comma-separated), e.g. the type picked in the event filter" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of resources to return" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string" }, "resourceId": { "type": "string" }, "name": { "type": "string" }, "detail": { "nullable": true, "description": "A second line to tell resources apart: the owner (agents, apps, MCP servers, skills) and the description, joined by ' · '. Null when neither is set or the resource's row is gone", "type": "string" } }, "required": [ "resourceType", "resourceId", "name", "detail" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "auditLog:read" ] } } }, "/api/audit-logs/{id}": { "get": { "operationId": "getAuditLog", "tags": [ "Audit Log" ], "description": "Get a single audit log event by ID. Requires auditLog:read permission (Admin only by default).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`auditLog:read`](/docs/reference/permissions#auditLog:read): View audit log records of your own administrative actions", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eventSequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "organizationId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actorId": { "nullable": true, "type": "string" }, "actorType": { "type": "string", "enum": [ "user", "api_key", "service_account", "system", "sso" ] }, "actorName": { "nullable": true, "type": "string" }, "actorEmail": { "nullable": true, "type": "string" }, "impersonatedBy": { "nullable": true, "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "resourcePermissions.updated", "hook.created", "hook.updated", "hook.deleted", "agent.created", "agent.updated", "agent.deleted", "agent.restored", "agent.imported", "agent.purged", "agent.bulk_deleted", "agentRun.created", "agentRun.canceled", "agentRun.updated", "agentRun.deleted", "agentRun.bulk_canceled", "agentRun.bulk_deleted", "agentRun.bulk_files_deleted", "agentRun.reviewDecided", "agentRun.terminal_attached", "agentRun.terminal_detached", "agentRun.terminal_interrupted", "blobProvider.created", "blobProvider.updated", "blobProvider.deleted", "blobProvider.tested", "browserStorageState.deleted", "costExport.created", "costExport.updated", "costExport.deleted", "costExport.run", "credential.created", "credential.updated", "credential.deleted", "agentTool.created", "agentTool.updated", "agentTool.deleted", "agentTool.bulk_assigned", "agentTool.bulk_removed", "agentTool.bulk_updated", "apiKey.created", "apiKey.deleted", "apiKey.bulk_deleted", "app.created", "app.updated", "app.deleted", "app.bulk_deleted", "chatOpsBinding.created", "chatOpsBinding.updated", "chatOpsBinding.deleted", "chatOpsBinding.refreshed", "chatOpsConfig.updated", "plugin.created", "plugin.updated", "plugin.deleted", "plugin.syncTriggered", "clientConnection.updated", "clientPrivacy.updated", "connectedClient.disconnected", "desktopDeviceSignIn.updated", "desktopDevice.updated", "desktopDevice.deleted", "connector.created", "connector.updated", "connector.deleted", "connector.restored", "connector.purged", "connector.bulk_updated", "connector.bulk_deleted", "connector.permission_sync_triggered", "connector.synced", "defaultUserLimit.created", "defaultUserLimit.updated", "defaultUserLimit.deleted", "environment.created", "environment.updated", "environment.deleted", "environment.bulk_deleted", "identityProvider.created", "identityProvider.updated", "identityProvider.deleted", "internalMcpCatalog.created", "internalMcpCatalog.updated", "internalMcpCatalog.deleted", "internalMcpCatalog.restored", "internalMcpCatalog.reinstalled", "invitation.created", "invitation.deleted", "knowledgeBase.created", "knowledgeBase.updated", "knowledgeBase.deleted", "knowledgeBase.restored", "knowledgeBase.purged", "knowledgeBase.bulk_deleted", "knowledgeDirectory.created", "knowledgeDirectory.updated", "knowledgeDirectory.deleted", "knowledgeDirectory.bulk_deleted", "knowledgeFile.created", "knowledgeFile.updated", "knowledgeFile.content_upserted", "knowledgeFile.deleted", "knowledgeFile.bulk_deleted", "limit.created", "limit.updated", "limit.reset", "limit.deleted", "limit.bulk_deleted", "llmModel.updated", "llmModel.deleted", "llmModel.synced", "llmModel.bulk_updated", "llmModel.cost_backfill_started", "modelPool.created", "modelPool.updated", "modelPool.deleted", "autoRouter.created", "autoRouter.updated", "autoRouter.deleted", "oauthClient.created", "oauthClient.updated", "oauthClient.deleted", "oauthClient.rotated", "oauthClient.bulk_deleted", "oauthClient.token_exchanged", "oauthClientFederatedCredential.created", "oauthClientFederatedCredential.updated", "oauthClientFederatedCredential.deleted", "llmProviderApiKey.created", "llmProviderApiKey.updated", "llmProviderApiKey.deleted", "llmProxy.updated", "llmProviderApiKey.bulk_deleted", "mcpServer.created", "mcpServer.updated", "mcpServer.deleted", "mcpServer.restored", "mcpServer.reinstalled", "mcpServer.hardReset", "mcpServer.bulk_deleted", "member.bulk_deleted", "member.created", "member.role_updated", "member.deleted", "organization.updated", "project.created", "project.updated", "project.deleted", "project.restored", "project.purged", "project.bulk_deleted", "role.created", "role.updated", "role.deleted", "role.bulk_deleted", "scheduleTrigger.created", "scheduleTrigger.updated", "scheduleTrigger.deleted", "scheduleTrigger.triggered", "serviceAccount.created", "serviceAccount.updated", "serviceAccount.deleted", "serviceAccount.bulk_deleted", "serviceAccount.bulk_updated", "serviceAccount.token_exchanged", "serviceAccountFederatedCredential.created", "serviceAccountFederatedCredential.updated", "serviceAccountFederatedCredential.deleted", "skill.created", "skill.updated", "skill.deleted", "skill.bulk_deleted", "skill.restored", "skill.purged", "skill.imported", "skillShareLink.created", "skillShareLink.rotated", "skillShareLink.revoked", "team.created", "team.updated", "team.deleted", "team.bulk_deleted", "guardrailsPolicy.updated", "openappaYell.updated", "openappaBatteryInstall.created", "openappaBatteryInstall.updated", "openappaBatteryInstall.deleted", "openappaBatteryPackage.updated", "openappaBatteryPackage.deleted", "openappaCredentialBinding.updated", "user.password_reset", "userToken.rotated", "userLimitUsage.reset", "virtualApiKey.created", "virtualApiKey.updated", "virtualApiKey.deleted", "virtualApiKey.bulk_deleted", "auth.impersonation_started", "auth.impersonation_stopped", "auth.signed_in", "auth.signed_out", "auth.signed_up", "auth.sso_callback", "auth.sessions_revoked", "unknown.created", "unknown.updated", "unknown.deleted" ] }, { "type": "string" } ] }, "outcome": { "type": "string", "enum": [ "success", "failure", "denied" ] }, "resourceType": { "nullable": true, "type": "string" }, "resourceId": { "nullable": true, "type": "string" }, "resourceName": { "nullable": true, "type": "string" }, "before": { "nullable": true, "type": "object", "additionalProperties": {} }, "after": { "nullable": true, "type": "object", "additionalProperties": {} }, "httpMethod": { "nullable": true, "type": "string" }, "httpPath": { "nullable": true, "type": "string" }, "httpRoute": { "nullable": true, "type": "string" }, "httpStatus": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "requestId": { "nullable": true, "type": "string" }, "sourceIp": { "nullable": true, "type": "string" }, "userAgent": { "nullable": true, "type": "string" }, "impersonatedByEmail": { "nullable": true, "type": "string" } }, "required": [ "id", "eventSequence", "organizationId", "occurredAt", "createdAt", "actorId", "actorType", "actorName", "actorEmail", "impersonatedBy", "action", "outcome", "resourceType", "resourceId", "resourceName", "before", "after", "httpMethod", "httpPath", "httpRoute", "httpStatus", "requestId", "sourceIp", "userAgent", "impersonatedByEmail" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "auditLog:read" ] } } }, "/api/auth-state": { "get": { "operationId": "getAuthState", "tags": [ "Auth" ], "description": "Report whether a two-factor sign-in challenge is currently pending\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "twoFactorPending": { "type": "boolean" } }, "required": [ "twoFactorPending" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/auth/default-credentials-status": { "get": { "operationId": "getDefaultCredentialsStatus", "tags": [ "Auth" ], "description": "Get default credentials status\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/auth/organization/remove-member": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/auth/oauth2/client-info": { "get": { "operationId": "getOAuthClientInfo", "tags": [ "Auth" ], "description": "Get OAuth client name by client_id\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "client_id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_name": { "nullable": true, "type": "string" } }, "required": [ "client_name" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/auth/oauth2/authorize": { "get": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/auth/oauth2/token": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/auth/oauth2/revoke": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/auth/oauth2/consent": { "post": { "operationId": "submitOAuthConsent", "tags": [ "Auth" ], "description": "Submit OAuth consent decision (accept or deny)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept": { "type": "boolean" }, "scope": { "type": "string" }, "oauth_query": { "type": "string" } }, "required": [ "accept", "scope", "oauth_query" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectTo": { "type": "string" } }, "required": [ "redirectTo" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/auth/oauth2/register": { "post": { "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/api/auth/sign-in/sso": { "post": { "tags": [ "Auth" ], "responses": { "200": { "description": "Default Response" } } } }, "/api/auth/{*}": { "get": { "tags": [ "Auth" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "tags": [ "Auth" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/auto-routing/state": { "get": { "operationId": "getAutoRoutingState", "tags": [ "Auto Routing" ], "description": "Get whether auto routing is on for the organization, and the keys and decision models its routers may use\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "eligibleApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "decisionProviders": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "displayName" ], "additionalProperties": false } }, "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "provider", "models", "apiKeys" ], "additionalProperties": false } } }, "required": [ "enabled", "eligibleApiKeyIds", "decisionProviders" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } }, "put": { "operationId": "updateAutoRoutingState", "tags": [ "Auto Routing" ], "description": "Turn auto routing on or off for the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "eligibleApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "decisionProviders": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "displayName" ], "additionalProperties": false } }, "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "provider", "models", "apiKeys" ], "additionalProperties": false } } }, "required": [ "enabled", "eligibleApiKeyIds", "decisionProviders" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/routers": { "get": { "operationId": "getAutoRouters", "tags": [ "Auto Routing" ], "description": "List the organization's auto routers with their planning status\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "budgetPreset": { "anyOf": [ { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "tiers": { "type": "object", "properties": { "fast": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "normal": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "smart": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string" } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false }, "usesPastSessions": { "type": "boolean" }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "usage": { "type": "object", "properties": { "agentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationDefault": { "type": "boolean" } }, "required": [ "agentCount", "organizationDefault" ], "additionalProperties": false }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plannedGeneration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "object", "properties": { "activePlan": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt" ], "additionalProperties": false }, "coldStart": { "type": "object", "properties": { "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "scorerVersionId", "sessions", "required" ], "additionalProperties": false }, "lastFitError": { "nullable": true, "type": "string" }, "scorer": { "type": "string", "enum": [ "ready", "no_jev_key" ] }, "scorerApiKey": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "activePlan", "coldStart", "lastFitError", "scorer", "scorerApiKey" ], "additionalProperties": false } }, "required": [ "id", "name", "enabled", "budgetUsdPerDay", "budgetPreset", "tiers", "decisionModel", "usesPastSessions", "virtualApiKeyIds", "usage", "generation", "plannedGeneration", "status" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } }, "post": { "operationId": "createAutoRouter", "tags": [ "Auto Routing" ], "description": "Create an auto router with its tiers, budget and decision model. It learns from its own sessions only\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^auto(:[a-z0-9][a-z0-9._-]{0,62})?$" }, "budgetUsdPerDay": { "type": "number", "minimum": 0.01, "maximum": 9999999999.99 }, "budgetPreset": { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, "tiers": { "type": "object", "properties": { "fast": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "modelId", "providerApiKeyId" ], "additionalProperties": false }, "normal": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "modelId", "providerApiKeyId" ], "additionalProperties": false }, "smart": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "modelId", "providerApiKeyId" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false } }, "required": [ "name", "tiers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "budgetPreset": { "anyOf": [ { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "tiers": { "type": "object", "properties": { "fast": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "normal": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "smart": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string" } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false }, "usesPastSessions": { "type": "boolean" }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "usage": { "type": "object", "properties": { "agentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationDefault": { "type": "boolean" } }, "required": [ "agentCount", "organizationDefault" ], "additionalProperties": false }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plannedGeneration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "object", "properties": { "activePlan": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt" ], "additionalProperties": false }, "coldStart": { "type": "object", "properties": { "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "scorerVersionId", "sessions", "required" ], "additionalProperties": false }, "lastFitError": { "nullable": true, "type": "string" }, "scorer": { "type": "string", "enum": [ "ready", "no_jev_key" ] }, "scorerApiKey": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "activePlan", "coldStart", "lastFitError", "scorer", "scorerApiKey" ], "additionalProperties": false }, "fit": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active" ] }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unchanged" ] }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cold_start" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "string" } }, "required": [ "status", "planId", "error" ], "additionalProperties": false } ] } }, "required": [ "id", "name", "enabled", "budgetUsdPerDay", "budgetPreset", "tiers", "decisionModel", "usesPastSessions", "virtualApiKeyIds", "usage", "generation", "plannedGeneration", "status", "fit" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/routers/available": { "get": { "operationId": "getAvailableAutoRouters", "tags": [ "Auto Routing" ], "description": "List the names of the organization's auto routers, for adding them to a virtual key\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:read`](/docs/reference/permissions#llmProviderApiKey:read): Open LLM provider API keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "id", "name", "virtualApiKeyIds" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:read" ] } } }, "/api/auto-routing/routers/{id}": { "get": { "operationId": "getAutoRouter", "tags": [ "Auto Routing" ], "description": "Get an auto router's settings and planning status\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "budgetPreset": { "anyOf": [ { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "tiers": { "type": "object", "properties": { "fast": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "normal": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "smart": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string" } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false }, "usesPastSessions": { "type": "boolean" }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "usage": { "type": "object", "properties": { "agentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationDefault": { "type": "boolean" } }, "required": [ "agentCount", "organizationDefault" ], "additionalProperties": false }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plannedGeneration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "object", "properties": { "activePlan": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt" ], "additionalProperties": false }, "coldStart": { "type": "object", "properties": { "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "scorerVersionId", "sessions", "required" ], "additionalProperties": false }, "lastFitError": { "nullable": true, "type": "string" }, "scorer": { "type": "string", "enum": [ "ready", "no_jev_key" ] }, "scorerApiKey": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "activePlan", "coldStart", "lastFitError", "scorer", "scorerApiKey" ], "additionalProperties": false } }, "required": [ "id", "name", "enabled", "budgetUsdPerDay", "budgetPreset", "tiers", "decisionModel", "usesPastSessions", "virtualApiKeyIds", "usage", "generation", "plannedGeneration", "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } }, "put": { "operationId": "updateAutoRouter", "tags": [ "Auto Routing" ], "description": "Update an auto router and fit a plan on it when auto routing is on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^auto(:[a-z0-9][a-z0-9._-]{0,62})?$" }, "budgetUsdPerDay": { "type": "number", "minimum": 0.01, "maximum": 9999999999.99 }, "budgetPreset": { "anyOf": [ { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "tiers": { "type": "object", "properties": { "fast": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "modelId", "providerApiKeyId" ], "additionalProperties": false }, "normal": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "modelId", "providerApiKeyId" ], "additionalProperties": false }, "smart": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "modelId", "providerApiKeyId" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "budgetPreset": { "anyOf": [ { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "tiers": { "type": "object", "properties": { "fast": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "normal": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "smart": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string" } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false }, "usesPastSessions": { "type": "boolean" }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "usage": { "type": "object", "properties": { "agentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationDefault": { "type": "boolean" } }, "required": [ "agentCount", "organizationDefault" ], "additionalProperties": false }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plannedGeneration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "object", "properties": { "activePlan": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt" ], "additionalProperties": false }, "coldStart": { "type": "object", "properties": { "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "scorerVersionId", "sessions", "required" ], "additionalProperties": false }, "lastFitError": { "nullable": true, "type": "string" }, "scorer": { "type": "string", "enum": [ "ready", "no_jev_key" ] }, "scorerApiKey": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "activePlan", "coldStart", "lastFitError", "scorer", "scorerApiKey" ], "additionalProperties": false }, "fit": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active" ] }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unchanged" ] }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cold_start" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "string" } }, "required": [ "status", "planId", "error" ], "additionalProperties": false } ] } }, "required": [ "id", "name", "enabled", "budgetUsdPerDay", "budgetPreset", "tiers", "decisionModel", "usesPastSessions", "virtualApiKeyIds", "usage", "generation", "plannedGeneration", "status", "fit" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } }, "delete": { "operationId": "deleteAutoRouter", "tags": [ "Auto Routing" ], "description": "Delete an auto router with its plans and what it learned. Agents, chats and keys set to it stop using it\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/routers/{id}/usage": { "get": { "operationId": "getAutoRoutingUsage", "tags": [ "Auto Routing" ], "description": "What an auto router routed over the last 7 or 14 days: sessions, requests and spend per tier, and the same tokens priced at its smart model\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "parameters": [ { "schema": { "default": 7, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "in": "query", "name": "days", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "windowDays": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number" }, "allSmartCostUsd": { "nullable": true, "type": "number" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "fast", "normal", "smart" ] }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "requests": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number" } }, "required": [ "tier", "sessions", "requests", "costUsd" ], "additionalProperties": false } } }, "required": [ "windowDays", "sessions", "requests", "costUsd", "allSmartCostUsd", "tiers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } } }, "/api/auto-routing/routers/{id}/plans": { "get": { "operationId": "getAutoRoutingPlans", "tags": [ "Auto Routing" ], "description": "List an auto router's fit outcomes, newest first\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "trigger": { "type": "string", "enum": [ "initial", "nightly", "settings", "manual", "scorer_change", "backfill" ] }, "status": { "type": "string", "enum": [ "active", "superseded", "failed", "cold_start", "rejected" ] }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inputWatermark": { "type": "string", "format": "date-time" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "scorerVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "model": { "type": "string" }, "specHash": { "type": "string" } }, "required": [ "id", "name", "model", "specHash" ], "additionalProperties": false }, "coreVersion": { "type": "string" }, "planFormatVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "summary": { "nullable": true, "type": "object", "additionalProperties": {} }, "diagnostics": { "nullable": true, "type": "object", "additionalProperties": {} }, "error": { "nullable": true, "type": "string" }, "decisionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "createdAt", "trigger", "status", "generation", "inputWatermark", "budgetUsdPerDay", "scorerVersion", "coreVersion", "planFormatVersion", "summary", "diagnostics", "error", "decisionCount" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } } }, "/api/auto-routing/routers/{id}/plans/{planId}": { "get": { "operationId": "getAutoRoutingPlan", "tags": [ "Auto Routing" ], "description": "Get one auto routing plan with its fitted models and policy\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "planId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "trigger": { "type": "string", "enum": [ "initial", "nightly", "settings", "manual", "scorer_change", "backfill" ] }, "status": { "type": "string", "enum": [ "active", "superseded", "failed", "cold_start", "rejected" ] }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inputWatermark": { "type": "string", "format": "date-time" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "scorerVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "model": { "type": "string" }, "specHash": { "type": "string" } }, "required": [ "id", "name", "model", "specHash" ], "additionalProperties": false }, "coreVersion": { "type": "string" }, "planFormatVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "summary": { "nullable": true, "type": "object", "additionalProperties": {} }, "diagnostics": { "nullable": true, "type": "object", "additionalProperties": {} }, "error": { "nullable": true, "type": "string" }, "decisionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tiersFingerprint": { "type": "object", "additionalProperties": {} }, "plan": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "id", "createdAt", "trigger", "status", "generation", "inputWatermark", "budgetUsdPerDay", "scorerVersion", "coreVersion", "planFormatVersion", "summary", "diagnostics", "error", "decisionCount", "tiersFingerprint", "plan" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } } }, "/api/auto-routing/routers/{id}/replan": { "post": { "operationId": "replanAutoRouting", "tags": [ "Auto Routing" ], "description": "Fit a new plan for an auto router at its current settings\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "budgetUsdPerDay": { "nullable": true, "type": "number" }, "budgetPreset": { "anyOf": [ { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "tiers": { "type": "object", "properties": { "fast": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "normal": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false }, "smart": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "provider", "modelId", "apiKey" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false }, "decisionModel": { "type": "object", "properties": { "apiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string" } }, "required": [ "apiKeyId", "model" ], "additionalProperties": false }, "usesPastSessions": { "type": "boolean" }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "usage": { "type": "object", "properties": { "agentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationDefault": { "type": "boolean" } }, "required": [ "agentCount", "organizationDefault" ], "additionalProperties": false }, "generation": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plannedGeneration": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "object", "properties": { "activePlan": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "createdAt" ], "additionalProperties": false }, "coldStart": { "type": "object", "properties": { "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "scorerVersionId", "sessions", "required" ], "additionalProperties": false }, "lastFitError": { "nullable": true, "type": "string" }, "scorer": { "type": "string", "enum": [ "ready", "no_jev_key" ] }, "scorerApiKey": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "activePlan", "coldStart", "lastFitError", "scorer", "scorerApiKey" ], "additionalProperties": false }, "fit": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active" ] }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unchanged" ] }, "planId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cold_start" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "planId" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "string" } }, "required": [ "status", "planId", "error" ], "additionalProperties": false } ] } }, "required": [ "id", "name", "enabled", "budgetUsdPerDay", "budgetPreset", "tiers", "decisionModel", "usesPastSessions", "virtualApiKeyIds", "usage", "generation", "plannedGeneration", "status", "fit" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/routers/{id}/preview": { "post": { "operationId": "previewAutoRouting", "tags": [ "Auto Routing" ], "description": "Score opening text or a request body with its system/tool context and show a fresh choice under the router's current plan, without executing the request or storing a decision\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "request": { "type": "object", "additionalProperties": {}, "description": "An opening Chat Completions, Responses or Anthropic Messages request body. Only its opening user text, system instructions and tool metadata are scored; the request is not executed." }, "client": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "request" ], "additionalProperties": false } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tierNeeded": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "minItems": 3, "maxItems": 3 }, "pLong": { "type": "number" }, "reason": { "type": "string", "enum": [ "planned", "cold_start", "plan_stale" ] }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chosen": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "fast", "normal", "smart" ] }, "model": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" } }, "required": [ "id", "provider", "modelId" ], "additionalProperties": false } }, "required": [ "tier", "model" ], "additionalProperties": false }, "propensity": { "type": "number" }, "expectedCostUsd": { "nullable": true, "type": "number" }, "scorerCostUsd": { "nullable": true, "type": "number" } }, "required": [ "tierNeeded", "pLong", "reason", "planId", "chosen", "propensity", "expectedCostUsd", "scorerCostUsd" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/routers/{id}/simulate": { "post": { "operationId": "simulateAutoRouting", "tags": [ "Auto Routing" ], "description": "Fit a plan for an auto router at a budget, or a budget preset, and a scaled traffic volume without publishing it\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "budgetUsdPerDay": { "type": "number", "minimum": 0.01, "maximum": 9999999999.99 }, "volumeMultiplier": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100 } }, "required": [ "budgetUsdPerDay", "volumeMultiplier" ], "additionalProperties": false }, { "type": "object", "properties": { "budgetPreset": { "type": "string", "enum": [ "cost_efficient", "balanced", "intelligence" ] }, "volumeMultiplier": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100 } }, "required": [ "budgetPreset", "volumeMultiplier" ], "additionalProperties": false } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "feasible" ] }, "budgetUsdPerDay": { "type": "number" }, "summary": { "type": "object", "additionalProperties": {} }, "tiersFingerprint": { "type": "object", "additionalProperties": {} }, "baseline": { "type": "object", "properties": { "sessionsPerDay": { "type": "number", "minimum": 0 }, "tokensPerDay": { "type": "number", "minimum": 0 } }, "required": [ "sessionsPerDay", "tokensPerDay" ], "additionalProperties": false } }, "required": [ "status", "budgetUsdPerDay", "summary", "tiersFingerprint", "baseline" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "infeasible" ] }, "minBudgetUsdPerDay": { "type": "number" }, "baseline": { "type": "object", "properties": { "sessionsPerDay": { "type": "number", "minimum": 0 }, "tokensPerDay": { "type": "number", "minimum": 0 } }, "required": [ "sessionsPerDay", "tokensPerDay" ], "additionalProperties": false } }, "required": [ "status", "minBudgetUsdPerDay", "baseline" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cold_start" ] }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "status", "sessions", "required" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_rate_limit_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } } }, "/api/auto-routing/routers/{id}/diagnostics": { "get": { "operationId": "getAutoRoutingDiagnostics", "tags": [ "Auto Routing" ], "description": "Re-solve an auto router's current fit history, at the active plan's scorer version and tiers, at a budget and return per-session estimates and routes, without publishing\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "parameters": [ { "schema": { "type": "number", "minimum": 0.01, "maximum": 9999999999.99 }, "in": "query", "name": "budgetUsdPerDay", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "budgetUsdPerDay": { "type": "number" }, "savedBudgetUsdPerDay": { "type": "number" }, "lamStar": { "type": "number" }, "q": { "type": "number" }, "tierSessionShare": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "minItems": 3, "maxItems": 3 }, "sizeFit": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "testSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "plotted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "excluded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spearman": { "nullable": true, "type": "number" }, "medianRealizedOverPredicted": { "nullable": true, "type": "number" } }, "required": [ "status", "testSessions", "plotted", "excluded", "spearman", "medianRealizedOverPredicted" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "no_holdout" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "failed" ] } }, "required": [ "status" ], "additionalProperties": false } ] }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "tierNeeded": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "minItems": 3, "maxItems": 3 }, "pLong": { "type": "number" }, "realizedTokens": { "type": "number" }, "predictedTokens": { "nullable": true, "type": "number" }, "usdPerToken": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "minItems": 3, "maxItems": 3 }, "tier": { "type": "string", "enum": [ "fast", "normal", "smart" ] } }, "required": [ "tierNeeded", "pLong", "realizedTokens", "predictedTokens", "usdPerToken", "tier" ], "additionalProperties": false } } }, "required": [ "status", "budgetUsdPerDay", "savedBudgetUsdPerDay", "lamStar", "q", "tierSessionShare", "sizeFit", "sessions" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "infeasible" ] }, "budgetUsdPerDay": { "type": "number" }, "savedBudgetUsdPerDay": { "type": "number" }, "minBudgetUsdPerDay": { "type": "number" } }, "required": [ "status", "budgetUsdPerDay", "savedBudgetUsdPerDay", "minBudgetUsdPerDay" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cold_start" ] } }, "required": [ "status" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_rate_limit_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } } }, "/api/auto-routing/backfill": { "get": { "operationId": "getAutoRoutingBackfill", "tags": [ "Auto Routing" ], "description": "Get the newest historical backfill and what scoring past sessions would take, for the organization's first auto router\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "backfill": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "eligibleSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleTokens": { "type": "number", "minimum": 0 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "apiShape": { "type": "string", "enum": [ "chat_completions", "responses", "messages" ] }, "client": { "type": "string" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "apiShape", "client", "sessions" ], "additionalProperties": false } }, "scorerCurrent": { "nullable": true, "type": "boolean" }, "maxSessions": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "number" }, "spentCostUsd": { "type": "number" }, "progress": { "nullable": true, "type": "object", "properties": { "sample": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "noText": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "sample", "scored", "noText", "failed" ], "additionalProperties": false }, "error": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "awaitingFit": { "type": "boolean" }, "fitBlockedReason": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "windowStart", "cutoff", "eligibleSessions", "eligibleTokens", "breakdown", "scorerCurrent", "maxSessions", "maxCostUsd", "spentCostUsd", "progress", "error", "completedAt", "awaitingFit", "fitBlockedReason" ], "additionalProperties": false }, "scoreOffer": { "nullable": true, "type": "object", "properties": { "backfillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "sessions": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "estimatedCostUsd": { "type": "number" }, "suggestedMaxCostUsd": { "type": "number" }, "rescore": { "type": "boolean" } }, "required": [ "backfillId", "scorerVersionId", "windowStart", "cutoff", "sessions", "remaining", "estimatedCostUsd", "suggestedMaxCostUsd", "rescore" ], "additionalProperties": false }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "startedByName": { "nullable": true, "type": "string" }, "foundSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scoredSessions": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spentCostUsd": { "type": "number" }, "maxCostUsd": { "nullable": true, "type": "number" }, "error": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "createdAt", "completedAt", "startedByName", "foundSessions", "scoredSessions", "spentCostUsd", "maxCostUsd", "error" ], "additionalProperties": false } } }, "required": [ "backfill", "scoreOffer", "history" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } }, "delete": { "operationId": "cancelAutoRoutingBackfill", "tags": [ "Auto Routing" ], "description": "Cancel the running historical backfill\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "backfill": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "eligibleSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleTokens": { "type": "number", "minimum": 0 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "apiShape": { "type": "string", "enum": [ "chat_completions", "responses", "messages" ] }, "client": { "type": "string" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "apiShape", "client", "sessions" ], "additionalProperties": false } }, "scorerCurrent": { "nullable": true, "type": "boolean" }, "maxSessions": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "number" }, "spentCostUsd": { "type": "number" }, "progress": { "nullable": true, "type": "object", "properties": { "sample": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "noText": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "sample", "scored", "noText", "failed" ], "additionalProperties": false }, "error": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "awaitingFit": { "type": "boolean" }, "fitBlockedReason": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "windowStart", "cutoff", "eligibleSessions", "eligibleTokens", "breakdown", "scorerCurrent", "maxSessions", "maxCostUsd", "spentCostUsd", "progress", "error", "completedAt", "awaitingFit", "fitBlockedReason" ], "additionalProperties": false }, "scoreOffer": { "nullable": true, "type": "object", "properties": { "backfillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "sessions": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "estimatedCostUsd": { "type": "number" }, "suggestedMaxCostUsd": { "type": "number" }, "rescore": { "type": "boolean" } }, "required": [ "backfillId", "scorerVersionId", "windowStart", "cutoff", "sessions", "remaining", "estimatedCostUsd", "suggestedMaxCostUsd", "rescore" ], "additionalProperties": false }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "startedByName": { "nullable": true, "type": "string" }, "foundSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scoredSessions": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spentCostUsd": { "type": "number" }, "maxCostUsd": { "nullable": true, "type": "number" }, "error": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "createdAt", "completedAt", "startedByName", "foundSessions", "scoredSessions", "spentCostUsd", "maxCostUsd", "error" ], "additionalProperties": false } } }, "required": [ "backfill", "scoreOffer", "history" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/backfill/scan": { "post": { "operationId": "scanAutoRoutingBackfill", "tags": [ "Auto Routing" ], "description": "Count the past sessions auto routing could learn from; reads the database only\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "backfill": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "eligibleSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleTokens": { "type": "number", "minimum": 0 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "apiShape": { "type": "string", "enum": [ "chat_completions", "responses", "messages" ] }, "client": { "type": "string" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "apiShape", "client", "sessions" ], "additionalProperties": false } }, "scorerCurrent": { "nullable": true, "type": "boolean" }, "maxSessions": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "number" }, "spentCostUsd": { "type": "number" }, "progress": { "nullable": true, "type": "object", "properties": { "sample": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "noText": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "sample", "scored", "noText", "failed" ], "additionalProperties": false }, "error": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "awaitingFit": { "type": "boolean" }, "fitBlockedReason": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "windowStart", "cutoff", "eligibleSessions", "eligibleTokens", "breakdown", "scorerCurrent", "maxSessions", "maxCostUsd", "spentCostUsd", "progress", "error", "completedAt", "awaitingFit", "fitBlockedReason" ], "additionalProperties": false }, "scoreOffer": { "nullable": true, "type": "object", "properties": { "backfillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "sessions": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "estimatedCostUsd": { "type": "number" }, "suggestedMaxCostUsd": { "type": "number" }, "rescore": { "type": "boolean" } }, "required": [ "backfillId", "scorerVersionId", "windowStart", "cutoff", "sessions", "remaining", "estimatedCostUsd", "suggestedMaxCostUsd", "rescore" ], "additionalProperties": false }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "startedByName": { "nullable": true, "type": "string" }, "foundSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scoredSessions": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spentCostUsd": { "type": "number" }, "maxCostUsd": { "nullable": true, "type": "number" }, "error": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "createdAt", "completedAt", "startedByName", "foundSessions", "scoredSessions", "spentCostUsd", "maxCostUsd", "error" ], "additionalProperties": false } } }, "required": [ "backfill", "scoreOffer", "history" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/auto-routing/backfill/score": { "post": { "operationId": "scoreAutoRoutingBackfill", "tags": [ "Auto Routing" ], "description": "Score a sample of the scanned past sessions with the session scorer, up to a USD ceiling\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "backfillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "maxSessions": { "default": 3000, "type": "integer", "minimum": 1, "maximum": 5000 }, "maxCostUsd": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 1000, "description": "Spending limit for the scorer calls in USD; may be exceeded by at most 4 × the per-call cost of the calls in flight" } }, "required": [ "backfillId", "scorerVersionId", "maxCostUsd" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "backfill": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "eligibleSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleTokens": { "type": "number", "minimum": 0 }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "apiShape": { "type": "string", "enum": [ "chat_completions", "responses", "messages" ] }, "client": { "type": "string" }, "sessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "apiShape", "client", "sessions" ], "additionalProperties": false } }, "scorerCurrent": { "nullable": true, "type": "boolean" }, "maxSessions": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "number" }, "spentCostUsd": { "type": "number" }, "progress": { "nullable": true, "type": "object", "properties": { "sample": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "noText": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "sample", "scored", "noText", "failed" ], "additionalProperties": false }, "error": { "nullable": true, "type": "string" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "awaitingFit": { "type": "boolean" }, "fitBlockedReason": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "windowStart", "cutoff", "eligibleSessions", "eligibleTokens", "breakdown", "scorerCurrent", "maxSessions", "maxCostUsd", "spentCostUsd", "progress", "error", "completedAt", "awaitingFit", "fitBlockedReason" ], "additionalProperties": false }, "scoreOffer": { "nullable": true, "type": "object", "properties": { "backfillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scorerVersionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "windowStart": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "sessions": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "estimatedCostUsd": { "type": "number" }, "suggestedMaxCostUsd": { "type": "number" }, "rescore": { "type": "boolean" } }, "required": [ "backfillId", "scorerVersionId", "windowStart", "cutoff", "sessions", "remaining", "estimatedCostUsd", "suggestedMaxCostUsd", "rescore" ], "additionalProperties": false }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "running", "scanned", "done", "failed", "cancelled", "superseded" ] }, "phase": { "type": "string", "enum": [ "scan", "score" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "startedByName": { "nullable": true, "type": "string" }, "foundSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "scoredSessions": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spentCostUsd": { "type": "number" }, "maxCostUsd": { "nullable": true, "type": "number" }, "error": { "nullable": true, "type": "string" } }, "required": [ "id", "status", "phase", "createdAt", "completedAt", "startedByName", "foundSessions", "scoredSessions", "spentCostUsd", "maxCostUsd", "error" ], "additionalProperties": false } } }, "required": [ "backfill", "scoreOffer", "history" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/v1/azure/files": { "post": { "operationId": "azureCreateFile", "tags": [ "LLM Proxy" ], "description": "Upload a bounded user_data file to the uniquely selected Azure account. File handles are principal/account scoped and support lifecycle operations only.\n\nAuthentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_after[anchor]": { "type": "string", "enum": [ "created_at" ] }, "expires_after[seconds]": { "type": "integer", "minimum": 3600, "maximum": 2592000 } }, "required": [ "file", "purpose" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "uploaded", "processed", "error", "pending", "running", "succeeded", "failed", "cancelled" ] } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "azureListFiles", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "api-version", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "query", "name": "after", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "string", "enum": [ "user_data" ] }, "in": "query", "name": "purpose", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "uploaded", "processed", "error", "pending", "running", "succeeded", "failed", "cancelled" ] } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "additionalProperties": false } }, "first_id": { "nullable": true, "type": "string" }, "last_id": { "nullable": true, "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "first_id", "last_id", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." } }, "/v1/azure/files/{fileId}": { "get": { "operationId": "azureRetrieveFile", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "uploaded", "processed", "error", "pending", "running", "succeeded", "failed", "cancelled" ] } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." }, "delete": { "operationId": "azureDeleteFile", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." } }, "/v1/azure/files/{fileId}/content": { "get": { "operationId": "azureFileContent", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." } }, "/v1/azure/{agentId}/files": { "post": { "operationId": "azureCreateFileWithAgent", "tags": [ "LLM Proxy" ], "description": "Upload a bounded user_data file to the uniquely selected Azure account. File handles are principal/account scoped and support lifecycle operations only.\n\nAuthentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_after[anchor]": { "type": "string", "enum": [ "created_at" ] }, "expires_after[seconds]": { "type": "integer", "minimum": 3600, "maximum": 2592000 } }, "required": [ "file", "purpose" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "uploaded", "processed", "error", "pending", "running", "succeeded", "failed", "cancelled" ] } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "azureListFilesWithAgent", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "api-version", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "query", "name": "after", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "order", "required": false }, { "schema": { "type": "string", "enum": [ "user_data" ] }, "in": "query", "name": "purpose", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "uploaded", "processed", "error", "pending", "running", "succeeded", "failed", "cancelled" ] } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "additionalProperties": false } }, "first_id": { "nullable": true, "type": "string" }, "last_id": { "nullable": true, "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "first_id", "last_id", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." } }, "/v1/azure/{agentId}/files/{fileId}": { "get": { "operationId": "azureRetrieveFileWithAgent", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "filename": { "type": "string" }, "purpose": { "type": "string", "enum": [ "user_data" ] }, "expires_at": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "uploaded", "processed", "error", "pending", "running", "succeeded", "failed", "cancelled" ] } }, "required": [ "id", "object", "bytes", "created_at", "filename", "purpose" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." }, "delete": { "operationId": "azureDeleteFileWithAgent", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "file" ] }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." } }, "/v1/azure/{agentId}/files/{fileId}/content": { "get": { "operationId": "azureFileContentWithAgent", "tags": [ "LLM Proxy" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "pattern": "^file-archestra-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "description": "Authentication:\n\nRequires an authenticated platform principal and one permitted configured Azure account. A provider key alone is insufficient. File handles are scoped to the principal, organization, and provider account. See [Azure Provider Files](/docs/llm-proxy/providers/azure#use-provider-files)." } }, "/v1/azure/audio/speech": { "post": { "operationId": "azureAudioSpeechWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Generate native audio bytes or audio SSE through the governed proxy. Usage and audio pricing may be unavailable.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "input": { "type": "string", "minLength": 1, "maxLength": 4096 }, "voice": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ] } }, "required": [ "model", "input", "voice" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/azure/{agentId}/audio/speech": { "post": { "operationId": "azureAudioSpeechWithAgent", "tags": [ "LLM Proxy" ], "description": "Generate native audio bytes or audio SSE through the governed proxy. Usage and audio pricing may be unavailable.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "input": { "type": "string", "minLength": 1, "maxLength": 4096 }, "voice": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ] } }, "required": [ "model", "input", "voice" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/azure/audio/transcriptions": { "post": { "operationId": "azureAudioTranscriptionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/azure/{agentId}/audio/transcriptions": { "post": { "operationId": "azureAudioTranscriptionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/azure/audio/translations": { "post": { "operationId": "azureAudioTranslationsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/azure/{agentId}/audio/translations": { "post": { "operationId": "azureAudioTranslationsWithAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/azure/images/edits": { "post": { "operationId": "azureImageEditsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Edit Azure images using bounded multipart image inputs and an optional PNG mask. Returns a complete image response; streaming is unsupported.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "anyOf": [ { "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, { "type": "null" } ] }, "background": { "anyOf": [ { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string", "enum": [ "url", "b64_json" ] }, { "type": "null" } ] }, "user": { "type": "string" }, "safety_identifier": { "type": [ "string", "null" ] }, "n": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "output_compression": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ] }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "null" } ] }, "image": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 16, "description": "PNG/JPEG/WebP reference files, each smaller than 50 MiB." }, "mask": { "type": "string", "format": "binary", "description": "Optional PNG alpha mask smaller than 4 MiB, matching the first image dimensions." } }, "required": [ "model", "prompt", "image" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/{agentId}/images/edits": { "post": { "operationId": "azureImageEditsWithAgent", "tags": [ "LLM Proxy" ], "description": "Edit Azure images using bounded multipart image inputs and an optional PNG mask. Returns a complete image response; streaming is unsupported.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "anyOf": [ { "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, { "type": "null" } ] }, "background": { "anyOf": [ { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string", "enum": [ "url", "b64_json" ] }, { "type": "null" } ] }, "user": { "type": "string" }, "safety_identifier": { "type": [ "string", "null" ] }, "n": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "output_compression": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ] }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "null" } ] }, "image": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 16, "description": "PNG/JPEG/WebP reference files, each smaller than 50 MiB." }, "mask": { "type": "string", "format": "binary", "description": "Optional PNG alpha mask smaller than 4 MiB, matching the first image dimensions." } }, "required": [ "model", "prompt", "image" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/realtime/turns": { "post": { "operationId": "azureRealtimeTurnWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a bounded realtime audio or translation turn through Azure native Realtime WebSockets. Returns Chat-format text and WAV audio; full-duplex sessions are not offered by this endpoint.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" }, "target_language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$" } }, "required": [ "model", "messages" ], "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." } } }, "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/{agentId}/realtime/turns": { "post": { "operationId": "azureRealtimeTurnWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a bounded realtime audio or translation turn through Azure native Realtime WebSockets. Returns Chat-format text and WAV audio; full-duplex sessions are not offered by this endpoint.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" }, "target_language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$" } }, "required": [ "model", "messages" ], "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." } } }, "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/images/generations": { "post": { "operationId": "azureImagesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Generate images with Azure AI Foundry\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/{agentId}/images/generations": { "post": { "operationId": "azureImagesWithAgent", "tags": [ "LLM Proxy" ], "description": "Generate images with Azure AI Foundry\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/embeddings": { "post": { "operationId": "azureEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Azure AI Foundry (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/{agentId}/embeddings": { "post": { "operationId": "azureEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Azure AI Foundry for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/chat/completions": { "post": { "operationId": "azureChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Azure AI Foundry (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/responses": { "post": { "operationId": "azureResponsesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with Azure AI Foundry (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/{agentId}/responses": { "post": { "operationId": "azureResponsesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with Azure AI Foundry for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/azure/{agentId}/chat/completions": { "post": { "operationId": "azureChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Azure AI Foundry for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "api-key", "required": false, "description": "Virtual API key for native Azure SDK clients" }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Azure AI Foundry" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/openai/chat/completions": { "post": { "operationId": "bedrockOpenaiChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Call Amazon Bedrock models using the OpenAI ChatCompletions wire format (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/bedrock/openai/{agentId}/chat/completions": { "post": { "operationId": "bedrockOpenaiChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Call Amazon Bedrock models using the OpenAI ChatCompletions wire format (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/bedrock/openai/models": { "get": { "operationId": "bedrockOpenaiListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List Amazon Bedrock models (via ListInferenceProfiles) in OpenAI models-list format\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token: Archestra virtual API key for Bedrock" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/openai/{agentId}/models": { "get": { "operationId": "bedrockOpenaiListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List Amazon Bedrock models (via ListInferenceProfiles) in OpenAI models-list format (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token: Archestra virtual API key for Bedrock" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/converse": { "post": { "operationId": "bedrockConverseWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Send a message to Amazon Bedrock using the default agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ] } }, "required": [ "toolUse" ] }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ] } }, "required": [ "toolResult" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "reasoningText" ] }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ] }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "redactedReasoning" ] } ] } }, "required": [ "reasoningContent" ] } ] } } }, "required": [ "role", "content" ] } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } }, "required": [ "name", "inputSchema" ] }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ] }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ] } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ] }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ] }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ] } }, "required": [ "jsonSchema" ] } }, "required": [ "type", "structure" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "$metadata": { "type": "object", "properties": { "httpStatusCode": { "type": "number" }, "requestId": { "type": "string" }, "attempts": { "type": "number" }, "totalRetryDelay": { "type": "number" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "additionalProperties": false }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered", "malformed_model_output", "malformed_tool_use", "model_context_window_exceeded" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadInputTokens": { "type": "number" }, "cacheWriteInputTokens": { "type": "number" }, "cacheDetails": { "type": "array", "items": { "type": "object", "properties": { "ttl": { "type": "string" }, "inputTokens": { "type": "number" } }, "additionalProperties": false } } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "number" } }, "additionalProperties": false }, "additionalModelResponseFields": { "type": "object", "additionalProperties": {} }, "trace": { "type": "object", "properties": { "guardrail": { "type": "object", "properties": { "inputAssessment": { "type": "object", "additionalProperties": {} }, "outputAssessments": { "type": "object", "additionalProperties": {} }, "modelOutput": { "type": "array", "items": { "type": "string" } }, "actionReason": { "type": "string" } }, "additionalProperties": false }, "promptRouter": { "type": "object", "properties": { "invokedModelId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false } }, "required": [ "output", "stopReason", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/{agentId}/converse": { "post": { "operationId": "bedrockConverseWithAgent", "tags": [ "LLM Proxy" ], "description": "Send a message to Amazon Bedrock for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ] } }, "required": [ "toolUse" ] }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ] } }, "required": [ "toolResult" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "reasoningText" ] }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ] }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "redactedReasoning" ] } ] } }, "required": [ "reasoningContent" ] } ] } } }, "required": [ "role", "content" ] } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } }, "required": [ "name", "inputSchema" ] }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ] }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ] } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ] }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ] }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ] } }, "required": [ "jsonSchema" ] } }, "required": [ "type", "structure" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "$metadata": { "type": "object", "properties": { "httpStatusCode": { "type": "number" }, "requestId": { "type": "string" }, "attempts": { "type": "number" }, "totalRetryDelay": { "type": "number" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "additionalProperties": false }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered", "malformed_model_output", "malformed_tool_use", "model_context_window_exceeded" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadInputTokens": { "type": "number" }, "cacheWriteInputTokens": { "type": "number" }, "cacheDetails": { "type": "array", "items": { "type": "object", "properties": { "ttl": { "type": "string" }, "inputTokens": { "type": "number" } }, "additionalProperties": false } } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "number" } }, "additionalProperties": false }, "additionalModelResponseFields": { "type": "object", "additionalProperties": {} }, "trace": { "type": "object", "properties": { "guardrail": { "type": "object", "properties": { "inputAssessment": { "type": "object", "additionalProperties": {} }, "outputAssessments": { "type": "object", "additionalProperties": {} }, "modelOutput": { "type": "array", "items": { "type": "string" } }, "actionReason": { "type": "string" } }, "additionalProperties": false }, "promptRouter": { "type": "object", "properties": { "invokedModelId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false } }, "required": [ "output", "stopReason", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/converse-stream": { "post": { "operationId": "bedrockConverseStreamWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Stream a message response from Amazon Bedrock using the default agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ] } }, "required": [ "toolUse" ] }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ] } }, "required": [ "toolResult" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "reasoningText" ] }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ] }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "redactedReasoning" ] } ] } }, "required": [ "reasoningContent" ] } ] } } }, "required": [ "role", "content" ] } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } }, "required": [ "name", "inputSchema" ] }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ] }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ] } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ] }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ] }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ] } }, "required": [ "jsonSchema" ] } }, "required": [ "type", "structure" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/bedrock/{agentId}/converse-stream": { "post": { "operationId": "bedrockConverseStreamWithAgent", "tags": [ "LLM Proxy" ], "description": "Stream a message response from Amazon Bedrock for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ] } }, "required": [ "toolUse" ] }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ] } }, "required": [ "toolResult" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "reasoningText" ] }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ] }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "redactedReasoning" ] } ] } }, "required": [ "reasoningContent" ] } ] } } }, "required": [ "role", "content" ] } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } }, "required": [ "name", "inputSchema" ] }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ] }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ] } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ] }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ] }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ] } }, "required": [ "jsonSchema" ] } }, "required": [ "type", "structure" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/bedrock/{agentId}/model/{modelId}/converse": { "post": { "operationId": "bedrockConverseWithAgentAndModel", "tags": [ "LLM Proxy" ], "description": "Send a message to Amazon Bedrock for a specific agent (AI SDK format)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ] } }, "required": [ "toolUse" ] }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ] } }, "required": [ "toolResult" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "reasoningText" ] }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ] }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "redactedReasoning" ] } ] } }, "required": [ "reasoningContent" ] } ] } } }, "required": [ "role", "content" ] } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } }, "required": [ "name", "inputSchema" ] }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ] }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ] } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ] }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ] }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ] } }, "required": [ "jsonSchema" ] } }, "required": [ "type", "structure" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "modelId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "$metadata": { "type": "object", "properties": { "httpStatusCode": { "type": "number" }, "requestId": { "type": "string" }, "attempts": { "type": "number" }, "totalRetryDelay": { "type": "number" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "additionalProperties": false }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered", "malformed_model_output", "malformed_tool_use", "model_context_window_exceeded" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadInputTokens": { "type": "number" }, "cacheWriteInputTokens": { "type": "number" }, "cacheDetails": { "type": "array", "items": { "type": "object", "properties": { "ttl": { "type": "string" }, "inputTokens": { "type": "number" } }, "additionalProperties": false } } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "number" } }, "additionalProperties": false }, "additionalModelResponseFields": { "type": "object", "additionalProperties": {} }, "trace": { "type": "object", "properties": { "guardrail": { "type": "object", "properties": { "inputAssessment": { "type": "object", "additionalProperties": {} }, "outputAssessments": { "type": "object", "additionalProperties": {} }, "modelOutput": { "type": "array", "items": { "type": "string" } }, "actionReason": { "type": "string" } }, "additionalProperties": false }, "promptRouter": { "type": "object", "properties": { "invokedModelId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false } }, "required": [ "output", "stopReason", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/{agentId}/model/{modelId}/converse-stream": { "post": { "operationId": "bedrockConverseStreamWithAgentAndModel", "tags": [ "LLM Proxy" ], "description": "Stream a message response from Amazon Bedrock for a specific agent (AI SDK format)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ] } }, "required": [ "toolUse" ] }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "source" ] } }, "required": [ "image" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ] }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ] } }, "required": [ "s3Location" ] } ] } }, "required": [ "format", "name", "source" ] } }, "required": [ "document" ] } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ] } }, "required": [ "toolResult" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ] } }, "required": [ "reasoningText" ] }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ] }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } }, "required": [ "redactedReasoning" ] } ] } }, "required": [ "reasoningContent" ] } ] } } }, "required": [ "role", "content" ] } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ] } }, "required": [ "text" ] } }, "required": [ "guardContent" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "cachePoint" ] }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } } }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } }, "required": [ "name", "inputSchema" ] }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ] }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ] }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ] } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ] }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ] }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ] } }, "required": [ "jsonSchema" ] } }, "required": [ "type", "structure" ] } } }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ] } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } } }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } } }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "modelId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/bedrock/model/{modelId}/invoke": { "post": { "operationId": "bedrockInvokeWithDefaultAgentAndModel", "tags": [ "LLM Proxy" ], "description": "Invoke an Anthropic model on Amazon Bedrock (Anthropic Messages format, default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "modelId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/{agentId}/model/{modelId}/invoke": { "post": { "operationId": "bedrockInvokeWithAgentAndModel", "tags": [ "LLM Proxy" ], "description": "Invoke an Anthropic model on Amazon Bedrock (Anthropic Messages format) for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "modelId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/bedrock/model/{modelId}/invoke-with-response-stream": { "post": { "operationId": "bedrockInvokeStreamWithDefaultAgentAndModel", "tags": [ "LLM Proxy" ], "description": "Stream an Anthropic model response from Amazon Bedrock (Anthropic Messages format, default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "modelId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/bedrock/{agentId}/model/{modelId}/invoke-with-response-stream": { "post": { "operationId": "bedrockInvokeStreamWithAgentAndModel", "tags": [ "LLM Proxy" ], "description": "Stream an Anthropic model response from Amazon Bedrock (Anthropic Messages format) for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "modelId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header with Bearer token" } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/blob-providers": { "get": { "operationId": "listBlobProviders", "tags": [ "Blob Providers" ], "description": "List the organization's blob providers. Credentials are never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "type": { "type": "string", "enum": [ "s3", "gcs", "azure_blob" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "bucket": { "type": "string" }, "region": { "type": "string" }, "keyPrefix": { "type": "string" }, "endpoint": { "nullable": true, "type": "string" }, "forcePathStyle": { "type": "boolean" }, "authMethod": { "type": "string", "enum": [ "default_chain", "access_key", "assume_role" ] }, "roleArn": { "nullable": true, "type": "string" }, "externalId": { "nullable": true, "type": "string" } }, "required": [ "type", "bucket", "region", "keyPrefix", "endpoint", "forcePathStyle", "authMethod", "roleArn", "externalId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gcs" ] }, "bucket": { "type": "string" }, "keyPrefix": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "application_default", "service_account_key" ] } }, "required": [ "type", "bucket", "keyPrefix", "authMethod" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "azure_blob" ] }, "accountName": { "type": "string" }, "container": { "type": "string" }, "keyPrefix": { "type": "string" }, "endpoint": { "nullable": true, "type": "string" }, "authMethod": { "type": "string", "enum": [ "default_credential", "service_principal", "account_key", "sas_token" ] }, "tenantId": { "nullable": true, "type": "string" }, "clientId": { "nullable": true, "type": "string" } }, "required": [ "type", "accountName", "container", "keyPrefix", "endpoint", "authMethod", "tenantId", "clientId" ], "additionalProperties": false } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredentials": { "type": "boolean", "description": "Whether static credentials are stored for this provider." }, "usedBy": { "type": "object", "properties": { "costExports": { "type": "array", "items": { "type": "string" }, "description": "Names of the cost exports that write to this provider." } }, "required": [ "costExports" ], "additionalProperties": false, "description": "What writes to this provider. A provider in use cannot be deleted." } }, "required": [ "id", "organizationId", "name", "type", "config", "createdAt", "updatedAt", "hasCredentials", "usedBy" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createBlobProvider", "tags": [ "Blob Providers" ], "description": "Configure a blob provider. Credentials are stored in the secrets manager.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "config": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "bucket": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 64 }, "keyPrefix": { "default": "", "type": "string", "maxLength": 512 }, "endpoint": { "nullable": true, "type": "string", "format": "uri" }, "forcePathStyle": { "default": false, "type": "boolean" }, "authMethod": { "type": "string", "enum": [ "default_chain", "access_key", "assume_role" ] }, "roleArn": { "nullable": true, "type": "string", "pattern": "^arn:[\\w-]+:iam::\\d{12}:role\\/.+$" }, "externalId": { "nullable": true, "type": "string", "maxLength": 1224 } }, "required": [ "type", "bucket", "region", "authMethod" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gcs" ] }, "bucket": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$" }, "keyPrefix": { "default": "", "type": "string", "maxLength": 512 }, "authMethod": { "type": "string", "enum": [ "application_default", "service_account_key" ] } }, "required": [ "type", "bucket", "authMethod" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "azure_blob" ] }, "accountName": { "type": "string", "pattern": "^[a-z0-9]{3,24}$" }, "container": { "type": "string", "pattern": "^(?!.*--)[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$" }, "keyPrefix": { "default": "", "type": "string", "maxLength": 512 }, "endpoint": { "nullable": true, "type": "string", "format": "uri" }, "authMethod": { "type": "string", "enum": [ "default_credential", "service_principal", "account_key", "sas_token" ] }, "tenantId": { "nullable": true, "type": "string", "maxLength": 64 }, "clientId": { "nullable": true, "type": "string", "maxLength": 64 } }, "required": [ "type", "accountName", "container", "authMethod" ] } ] }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Write-only secrets for the auth method: `accessKeyId`, `secretAccessKey`, `sessionToken` (S3); `serviceAccountKey` (GCS); `clientSecret`, `accountKey` or `sasToken` (Azure)." }, "skipConnectionTest": { "description": "Save without first writing and deleting a test object. By default a failed test rejects the request.", "type": "boolean" } }, "required": [ "name", "config" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "type": { "type": "string", "enum": [ "s3", "gcs", "azure_blob" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "bucket": { "type": "string" }, "region": { "type": "string" }, "keyPrefix": { "type": "string" }, "endpoint": { "nullable": true, "type": "string" }, "forcePathStyle": { "type": "boolean" }, "authMethod": { "type": "string", "enum": [ "default_chain", "access_key", "assume_role" ] }, "roleArn": { "nullable": true, "type": "string" }, "externalId": { "nullable": true, "type": "string" } }, "required": [ "type", "bucket", "region", "keyPrefix", "endpoint", "forcePathStyle", "authMethod", "roleArn", "externalId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gcs" ] }, "bucket": { "type": "string" }, "keyPrefix": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "application_default", "service_account_key" ] } }, "required": [ "type", "bucket", "keyPrefix", "authMethod" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "azure_blob" ] }, "accountName": { "type": "string" }, "container": { "type": "string" }, "keyPrefix": { "type": "string" }, "endpoint": { "nullable": true, "type": "string" }, "authMethod": { "type": "string", "enum": [ "default_credential", "service_principal", "account_key", "sas_token" ] }, "tenantId": { "nullable": true, "type": "string" }, "clientId": { "nullable": true, "type": "string" } }, "required": [ "type", "accountName", "container", "keyPrefix", "endpoint", "authMethod", "tenantId", "clientId" ], "additionalProperties": false } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredentials": { "type": "boolean", "description": "Whether static credentials are stored for this provider." }, "usedBy": { "type": "object", "properties": { "costExports": { "type": "array", "items": { "type": "string" }, "description": "Names of the cost exports that write to this provider." } }, "required": [ "costExports" ], "additionalProperties": false, "description": "What writes to this provider. A provider in use cannot be deleted." } }, "required": [ "id", "organizationId", "name", "type", "config", "createdAt", "updatedAt", "hasCredentials", "usedBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/blob-providers/{id}": { "put": { "operationId": "updateBlobProvider", "tags": [ "Blob Providers" ], "description": "Update a blob provider. Send credentials only to replace them.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "config": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "bucket": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 64 }, "keyPrefix": { "default": "", "type": "string", "maxLength": 512 }, "endpoint": { "nullable": true, "type": "string", "format": "uri" }, "forcePathStyle": { "default": false, "type": "boolean" }, "authMethod": { "type": "string", "enum": [ "default_chain", "access_key", "assume_role" ] }, "roleArn": { "nullable": true, "type": "string", "pattern": "^arn:[\\w-]+:iam::\\d{12}:role\\/.+$" }, "externalId": { "nullable": true, "type": "string", "maxLength": 1224 } }, "required": [ "type", "bucket", "region", "authMethod" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gcs" ] }, "bucket": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$" }, "keyPrefix": { "default": "", "type": "string", "maxLength": 512 }, "authMethod": { "type": "string", "enum": [ "application_default", "service_account_key" ] } }, "required": [ "type", "bucket", "authMethod" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "azure_blob" ] }, "accountName": { "type": "string", "pattern": "^[a-z0-9]{3,24}$" }, "container": { "type": "string", "pattern": "^(?!.*--)[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$" }, "keyPrefix": { "default": "", "type": "string", "maxLength": 512 }, "endpoint": { "nullable": true, "type": "string", "format": "uri" }, "authMethod": { "type": "string", "enum": [ "default_credential", "service_principal", "account_key", "sas_token" ] }, "tenantId": { "nullable": true, "type": "string", "maxLength": 64 }, "clientId": { "nullable": true, "type": "string", "maxLength": 64 } }, "required": [ "type", "accountName", "container", "authMethod" ] } ] }, "credentials": { "description": "Write-only. Send only to replace the stored credentials.", "type": "object", "additionalProperties": { "type": "string" } }, "clearCredentials": { "description": "Remove the stored credentials.", "type": "boolean" }, "skipConnectionTest": { "description": "Save without first writing and deleting a test object. By default a failed test rejects the request.", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "type": { "type": "string", "enum": [ "s3", "gcs", "azure_blob" ] }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "s3" ] }, "bucket": { "type": "string" }, "region": { "type": "string" }, "keyPrefix": { "type": "string" }, "endpoint": { "nullable": true, "type": "string" }, "forcePathStyle": { "type": "boolean" }, "authMethod": { "type": "string", "enum": [ "default_chain", "access_key", "assume_role" ] }, "roleArn": { "nullable": true, "type": "string" }, "externalId": { "nullable": true, "type": "string" } }, "required": [ "type", "bucket", "region", "keyPrefix", "endpoint", "forcePathStyle", "authMethod", "roleArn", "externalId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gcs" ] }, "bucket": { "type": "string" }, "keyPrefix": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "application_default", "service_account_key" ] } }, "required": [ "type", "bucket", "keyPrefix", "authMethod" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "azure_blob" ] }, "accountName": { "type": "string" }, "container": { "type": "string" }, "keyPrefix": { "type": "string" }, "endpoint": { "nullable": true, "type": "string" }, "authMethod": { "type": "string", "enum": [ "default_credential", "service_principal", "account_key", "sas_token" ] }, "tenantId": { "nullable": true, "type": "string" }, "clientId": { "nullable": true, "type": "string" } }, "required": [ "type", "accountName", "container", "keyPrefix", "endpoint", "authMethod", "tenantId", "clientId" ], "additionalProperties": false } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "hasCredentials": { "type": "boolean", "description": "Whether static credentials are stored for this provider." }, "usedBy": { "type": "object", "properties": { "costExports": { "type": "array", "items": { "type": "string" }, "description": "Names of the cost exports that write to this provider." } }, "required": [ "costExports" ], "additionalProperties": false, "description": "What writes to this provider. A provider in use cannot be deleted." } }, "required": [ "id", "organizationId", "name", "type", "config", "createdAt", "updatedAt", "hasCredentials", "usedBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "delete": { "operationId": "deleteBlobProvider", "tags": [ "Blob Providers" ], "description": "Delete a blob provider and its credentials. Rejected while a cost export writes to it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/blob-providers/{id}/test": { "post": { "operationId": "testBlobProvider", "tags": [ "Blob Providers" ], "description": "Check a blob provider by writing and deleting a small test object under its prefix.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/bootstrap": { "get": { "operationId": "getBootstrap", "tags": [ "Config" ], "description": "Get the signed-in user's permissions, organization, platform config, appearance settings, and chat defaults in one request\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } }, "scopedCapabilities": { "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "resource": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "action": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "required": [ "organizationId", "resource", "scope", "action" ], "additionalProperties": false } }, "organization": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false }, "config": { "type": "object", "properties": { "version": { "type": "string" }, "enterpriseFeatures": { "type": "object", "properties": { "core": { "type": "boolean" }, "knowledgeBase": { "type": "boolean" }, "fullWhiteLabeling": { "type": "boolean" } }, "required": [ "core", "knowledgeBase", "fullWhiteLabeling" ], "additionalProperties": false }, "smallTeamTier": { "type": "object", "properties": { "threshold": { "type": "number" }, "userCount": { "type": "number" }, "smallTeam": { "type": "boolean" }, "envFlag": { "type": "boolean" }, "communicate": { "type": "boolean" } }, "required": [ "threshold", "userCount", "smallTeam", "envFlag", "communicate" ], "additionalProperties": false }, "features": { "type": "object", "properties": { "orchestratorK8sRuntime": { "type": "boolean" }, "agentIdentitySpiffe": { "type": "object", "properties": { "trustDomain": { "type": "string" }, "issuer": { "type": "string" }, "jwksUri": { "type": "string" }, "bundleUri": { "type": "string" } }, "required": [ "trustDomain", "issuer", "jwksUri", "bundleUri" ], "additionalProperties": false }, "mcpIdleHibernationBetaEnabled": { "deprecated": true, "description": "Deprecated. Always true: MCP idle hibernation is generally available. Kept for backward compatibility.", "type": "boolean" }, "sandbox": { "type": "boolean" }, "agentRuntime": { "type": "boolean" }, "agentRuntimeCatalogImages": { "type": "object", "additionalProperties": { "type": "string" } }, "agentRuntimeBackend": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "kubernetes" ] }, "available": { "type": "boolean" }, "defaultTtlHours": { "type": "number" }, "defaultIdleTimeoutMinutes": { "type": "number" }, "allowPrivileged": { "type": "boolean" } }, "required": [ "name", "available", "defaultTtlHours", "defaultIdleTimeoutMinutes", "allowPrivileged" ], "additionalProperties": false }, "plugins": { "type": "boolean" }, "sandboxArtifactBytesLimit": { "type": "number" }, "chatAttachmentStorageBytesLimit": { "type": "number" }, "apiBodyLimitBytes": { "type": "number" }, "azureOpenAiEntraIdEnabled": { "type": "boolean" }, "anthropicWifEnabled": { "type": "boolean" }, "anthropicKeylessAuthEnabled": { "type": "boolean" }, "anthropicVertexAiEnabled": { "type": "boolean" }, "bedrockIamAuthEnabled": { "type": "boolean" }, "geminiVertexAiEnabled": { "type": "boolean" }, "incomingEmail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "outlook" ] }, "displayName": { "type": "string" }, "emailDomain": { "type": "string" } }, "required": [ "enabled" ], "additionalProperties": false }, "mcpServerBaseImage": { "type": "string" }, "orchestratorK8sNamespace": { "type": "string" }, "environmentNamespaces": { "type": "array", "items": { "type": "string" } }, "isQuickstart": { "type": "boolean" }, "ngrokDomain": { "type": "string" }, "virtualKeyDefaultExpirationSeconds": { "type": "number" }, "mcpSandboxDomain": { "nullable": true, "type": "string" }, "maintenanceMode": { "nullable": true, "type": "string" }, "chatSecretScanEnabled": { "type": "boolean" }, "encryptedChatEnabled": { "type": "boolean" }, "openappaEnabled": { "type": "boolean" }, "agentHooksEnabled": { "type": "boolean" }, "chatopsTelegramEnabled": { "type": "boolean" }, "kbMfilesConnectorEnabled": { "type": "boolean" }, "kbMfilesOauthEnabled": { "type": "boolean" }, "kbBm25DefaultK1": { "type": "number" }, "kbBm25DefaultB": { "type": "number" }, "kbContextualRetrievalDefaultMode": { "$ref": "#/components/schemas/ContextualRetrievalMode" }, "kbGoogleDriveOAuth": { "type": "object", "properties": { "configured": { "type": "boolean" }, "redirectUri": { "type": "string" } }, "required": [ "configured", "redirectUri" ], "additionalProperties": false }, "devFeedbackEnabled": { "type": "boolean" } }, "required": [ "orchestratorK8sRuntime", "agentIdentitySpiffe", "sandbox", "agentRuntime", "agentRuntimeCatalogImages", "agentRuntimeBackend", "plugins", "sandboxArtifactBytesLimit", "chatAttachmentStorageBytesLimit", "apiBodyLimitBytes", "azureOpenAiEntraIdEnabled", "anthropicWifEnabled", "anthropicKeylessAuthEnabled", "anthropicVertexAiEnabled", "bedrockIamAuthEnabled", "geminiVertexAiEnabled", "incomingEmail", "mcpServerBaseImage", "orchestratorK8sNamespace", "environmentNamespaces", "isQuickstart", "ngrokDomain", "virtualKeyDefaultExpirationSeconds", "mcpSandboxDomain", "maintenanceMode", "chatSecretScanEnabled", "encryptedChatEnabled", "openappaEnabled", "agentHooksEnabled", "chatopsTelegramEnabled", "kbMfilesConnectorEnabled", "kbMfilesOauthEnabled", "kbBm25DefaultK1", "kbBm25DefaultB", "kbContextualRetrievalDefaultMode", "kbGoogleDriveOAuth", "devFeedbackEnabled" ], "additionalProperties": false }, "providerBaseUrls": { "type": "object", "additionalProperties": { "nullable": true, "type": "string" }, "required": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] } }, "required": [ "version", "enterpriseFeatures", "smallTeamTier", "features", "providerBaseUrls" ], "additionalProperties": false }, "publicConfig": { "type": "object", "properties": { "disableBasicAuth": { "type": "boolean" }, "disableInvitations": { "type": "boolean" }, "disableImpersonation": { "type": "boolean" }, "devAutoLoginEnabled": { "type": "boolean" }, "maintenanceMode": { "nullable": true, "type": "string" }, "siteNotificationMessage": { "nullable": true, "type": "string" }, "enterpriseCoreActive": { "type": "boolean" }, "analytics": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "instanceId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "posthog": { "type": "object", "properties": { "key": { "type": "string" }, "host": { "type": "string" } }, "required": [ "key", "host" ], "additionalProperties": false } }, "required": [ "enabled", "instanceId", "posthog" ], "additionalProperties": false }, "rum": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "sampleRate": { "type": "number" } }, "required": [ "enabled", "sampleRate" ], "additionalProperties": false } }, "required": [ "disableBasicAuth", "disableInvitations", "disableImpersonation", "devAutoLoginEnabled", "maintenanceMode", "siteNotificationMessage", "enterpriseCoreActive", "analytics", "rum" ], "additionalProperties": false }, "appearance": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "favicon": { "nullable": true, "type": "string" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "animateChatPlaceholders": { "type": "boolean" } }, "required": [ "theme", "customFont", "logo", "logoDark", "favicon", "iconLogo", "iconLogoDark", "appName", "ogDescription", "footerText", "chatLinks", "chatErrorSupportMessage", "slimChatErrorUi", "animateChatPlaceholders" ], "additionalProperties": false }, "memberDefaultAgent": { "type": "object", "properties": { "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "personalChatAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "defaultAgentId", "personalChatAgentId" ], "additionalProperties": false } }, "required": [ "permissions", "scopedCapabilities", "organization", "config", "publicConfig", "appearance", "memberDefaultAgent" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/bootstrap/new-chat": { "get": { "operationId": "getNewChatBootstrap", "tags": [ "Config" ], "description": "Get the new-chat composer's agents, provider keys, models, and the starting agent's details in one request\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "roster": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "builtIn": { "nullable": true, "type": "boolean" }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sharedByName": { "type": "boolean" } }, "required": [ "id", "organizationId", "name", "description", "icon", "scope", "authorId", "agentType", "builtIn", "builtInAgentConfig", "runtime", "modelId", "llmApiKeyId", "modelPoolId", "autoRouterId", "sharedByName" ], "additionalProperties": false } }, "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } }, "availableApiKeys": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dbId": { "type": "string" }, "displayName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "createdAt": { "type": "string" }, "capabilities": { "type": "object", "properties": { "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "outputLength": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "supportedEndpoints": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses" ] } }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "recommendedForAgents": { "nullable": true, "type": "boolean" }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isCustomPrice": { "type": "boolean" }, "priceSource": { "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "cachePriceSource": { "nullable": true, "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "mediaPricing": { "nullable": true, "type": "object", "properties": { "per": { "type": "string", "enum": [ "million_tokens", "million_characters", "minute" ] }, "input": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } }, "output": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } } }, "required": [ "per", "input", "output" ], "additionalProperties": false } }, "required": [ "contextLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "outputLength", "supportedReasoningEfforts", "recommendedForAgents", "pricePerMillionInput", "pricePerMillionOutput", "isCustomPrice", "priceSource", "pricePerMillionCacheRead", "pricePerMillionCacheWrite", "cachePriceSource", "mediaPricing" ], "additionalProperties": false }, "isBest": { "type": "boolean" }, "isFree": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "requiresUserConnection": { "type": "boolean" }, "isConnected": { "type": "boolean" } }, "required": [ "id", "dbId", "displayName", "provider", "isFree" ], "additionalProperties": false } }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "detail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "systemPrompt" ], "additionalProperties": false } }, "credentialReadiness": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "missingConnections": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "catalogName": { "type": "string" } }, "required": [ "catalogId", "catalogName" ], "additionalProperties": false } } }, "required": [ "agentId", "missingCredentialBehavior", "missingConnections" ], "additionalProperties": false } }, "browserTools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "description": { "nullable": true, "type": "string" }, "meta": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "clonedPendingDiscovery": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description", "meta", "clonedPendingDiscovery", "createdAt", "updatedAt", "deletedAt", "mcpServerId", "credentialResolutionMode" ], "additionalProperties": false } }, "defaultSuggestedPrompts": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "keyModels": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dbId": { "type": "string" }, "displayName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "createdAt": { "type": "string" }, "capabilities": { "type": "object", "properties": { "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "outputLength": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "supportedEndpoints": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses" ] } }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "recommendedForAgents": { "nullable": true, "type": "boolean" }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isCustomPrice": { "type": "boolean" }, "priceSource": { "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "cachePriceSource": { "nullable": true, "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "mediaPricing": { "nullable": true, "type": "object", "properties": { "per": { "type": "string", "enum": [ "million_tokens", "million_characters", "minute" ] }, "input": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } }, "output": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } } }, "required": [ "per", "input", "output" ], "additionalProperties": false } }, "required": [ "contextLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "outputLength", "supportedReasoningEfforts", "recommendedForAgents", "pricePerMillionInput", "pricePerMillionOutput", "isCustomPrice", "priceSource", "pricePerMillionCacheRead", "pricePerMillionCacheWrite", "cachePriceSource", "mediaPricing" ], "additionalProperties": false }, "isBest": { "type": "boolean" }, "isFree": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "requiresUserConnection": { "type": "boolean" }, "isConnected": { "type": "boolean" } }, "required": [ "id", "dbId", "displayName", "provider", "isFree" ], "additionalProperties": false } } }, "required": [ "id", "detail", "delegations", "credentialReadiness", "browserTools", "defaultSuggestedPrompts", "keyModels" ], "additionalProperties": false } }, "required": [ "roster", "apiKeys", "availableApiKeys", "models", "agent" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/bootstrap/conversation/{id}": { "get": { "operationId": "getConversationBootstrap", "tags": [ "Config" ], "description": "Get the end of a conversation and its composer's agent, keys and models in one request\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false }, "composer": { "type": "object", "properties": { "roster": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "builtIn": { "nullable": true, "type": "boolean" }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sharedByName": { "type": "boolean" } }, "required": [ "id", "organizationId", "name", "description", "icon", "scope", "authorId", "agentType", "builtIn", "builtInAgentConfig", "runtime", "modelId", "llmApiKeyId", "modelPoolId", "autoRouterId", "sharedByName" ], "additionalProperties": false } }, "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } }, "availableApiKeys": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dbId": { "type": "string" }, "displayName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "createdAt": { "type": "string" }, "capabilities": { "type": "object", "properties": { "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "outputLength": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "supportedEndpoints": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses" ] } }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "recommendedForAgents": { "nullable": true, "type": "boolean" }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isCustomPrice": { "type": "boolean" }, "priceSource": { "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "cachePriceSource": { "nullable": true, "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "mediaPricing": { "nullable": true, "type": "object", "properties": { "per": { "type": "string", "enum": [ "million_tokens", "million_characters", "minute" ] }, "input": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } }, "output": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } } }, "required": [ "per", "input", "output" ], "additionalProperties": false } }, "required": [ "contextLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "outputLength", "supportedReasoningEfforts", "recommendedForAgents", "pricePerMillionInput", "pricePerMillionOutput", "isCustomPrice", "priceSource", "pricePerMillionCacheRead", "pricePerMillionCacheWrite", "cachePriceSource", "mediaPricing" ], "additionalProperties": false }, "isBest": { "type": "boolean" }, "isFree": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "requiresUserConnection": { "type": "boolean" }, "isConnected": { "type": "boolean" } }, "required": [ "id", "dbId", "displayName", "provider", "isFree" ], "additionalProperties": false } }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "detail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "isDefault": { "type": "boolean" }, "isPersonalGateway": { "type": "boolean" }, "isPersonalProxy": { "type": "boolean" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "systemPrompt": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "incomingEmailEnabled": { "type": "boolean" }, "incomingEmailSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "incomingEmailAllowedDomain": { "nullable": true, "type": "string" }, "llmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmModel": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "runtime": { "nullable": true, "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "maxLength": 2000 }, "command": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "steerMode": { "type": "string", "enum": [ "pipe", "tmux_keys" ] }, "privileged": { "type": "boolean" }, "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "maxTier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "ports": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "environment": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "credentials": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Z_][A-Z0-9_]*$" }, "scope": { "type": "string", "enum": [ "shared", "per_user" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "required": { "type": "boolean" } }, "required": [ "key", "scope", "label", "required" ], "additionalProperties": false } }, "allowAgentSuppliedCredentialValues": { "type": "boolean" }, "claudeCode": { "type": "object", "properties": { "authentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "authentication" ], "additionalProperties": false }, "ttlHours": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 720 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 100000 }, "idleTimeoutMinutes": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "image", "command", "inferenceProtocol", "backend", "steerMode", "privileged", "environment", "credentials", "ttlHours", "idleTimeoutMinutes" ], "additionalProperties": false }, "runtimeSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughHeaders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "githubActionsAccess": { "nullable": true, "type": "object", "properties": { "githubAppCredentialKey": { "type": "string" }, "repositories": { "type": "array", "items": { "type": "string" } }, "actAs": { "type": "string", "enum": [ "author", "actor" ] }, "resolveReviewThreads": { "type": "boolean" }, "workflows": { "type": "array", "items": { "type": "string" } } }, "required": [ "githubAppCredentialKey", "repositories", "workflows" ], "additionalProperties": false }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "accessAllTools": { "type": "boolean" }, "accessAllSkills": { "type": "boolean" }, "activationSkillMode": { "type": "string", "enum": [ "all", "manual" ] }, "activationSkillPolicyRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "accessAllSubagents": { "type": "boolean" }, "subagentLoadBalancing": { "nullable": true, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "algorithm": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "weighted", "random" ] }, "weights": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "retries": { "default": 3, "type": "integer", "minimum": 0, "maximum": 3 }, "fallbackEnabled": { "default": true, "type": "boolean" } }, "required": [ "enabled", "algorithm", "retries", "fallbackEnabled" ], "additionalProperties": false }, "builtInAgentConfig": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "openappa-configuration-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "context-compaction-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "chat-title-generation-subagent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "app-runtime-llm-agent" ] } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "sre-agent" ] } }, "required": [ "name" ], "additionalProperties": false } ] }, "builtIn": { "nullable": true, "type": "boolean" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "authorEmail": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "connectorIds": { "type": "array", "items": { "type": "string" } }, "suggestedPrompts": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "resolvedLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "resolvedLlmProviderKeyName": { "nullable": true, "type": "string" }, "resolvedLlmModelName": { "nullable": true, "type": "string" }, "llmProviderRequiresPerUserCredential": { "type": "boolean" }, "sandboxAvailable": { "type": "boolean" }, "activationSkillsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "slug", "isDefault", "isPersonalGateway", "isPersonalProxy", "agentType", "systemPrompt", "description", "icon", "incomingEmailEnabled", "incomingEmailSecurityMode", "incomingEmailAllowedDomain", "llmApiKeyId", "llmModel", "modelId", "modelPoolId", "autoRouterId", "identityProviderId", "environmentId", "runtime", "runtimeSecretId", "passthroughHeaders", "toolExposureMode", "missingCredentialBehavior", "accessAllTools", "accessAllSkills", "activationSkillMode", "activationSkillPolicyRevision", "accessAllSubagents", "builtInAgentConfig", "builtIn", "latestVersion", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "tools", "teams", "labels", "knowledgeBaseIds", "connectorIds", "suggestedPrompts" ], "additionalProperties": false }, "delegations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "systemPrompt" ], "additionalProperties": false } }, "credentialReadiness": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "missingCredentialBehavior": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "missingConnections": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "catalogName": { "type": "string" } }, "required": [ "catalogId", "catalogName" ], "additionalProperties": false } } }, "required": [ "agentId", "missingCredentialBehavior", "missingConnections" ], "additionalProperties": false } }, "browserTools": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "description": { "nullable": true, "type": "string" }, "meta": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "clonedPendingDiscovery": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "mcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "id", "agentId", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description", "meta", "clonedPendingDiscovery", "createdAt", "updatedAt", "deletedAt", "mcpServerId", "credentialResolutionMode" ], "additionalProperties": false } }, "defaultSuggestedPrompts": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "summaryTitle": { "type": "string", "minLength": 1, "maxLength": 50 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "summaryTitle", "prompt" ], "additionalProperties": false } }, "keyModels": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dbId": { "type": "string" }, "displayName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "createdAt": { "type": "string" }, "capabilities": { "type": "object", "properties": { "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "outputLength": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "supportedEndpoints": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses" ] } }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "recommendedForAgents": { "nullable": true, "type": "boolean" }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isCustomPrice": { "type": "boolean" }, "priceSource": { "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "cachePriceSource": { "nullable": true, "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "mediaPricing": { "nullable": true, "type": "object", "properties": { "per": { "type": "string", "enum": [ "million_tokens", "million_characters", "minute" ] }, "input": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } }, "output": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } } }, "required": [ "per", "input", "output" ], "additionalProperties": false } }, "required": [ "contextLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "outputLength", "supportedReasoningEfforts", "recommendedForAgents", "pricePerMillionInput", "pricePerMillionOutput", "isCustomPrice", "priceSource", "pricePerMillionCacheRead", "pricePerMillionCacheWrite", "cachePriceSource", "mediaPricing" ], "additionalProperties": false }, "isBest": { "type": "boolean" }, "isFree": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "requiresUserConnection": { "type": "boolean" }, "isConnected": { "type": "boolean" } }, "required": [ "id", "dbId", "displayName", "provider", "isFree" ], "additionalProperties": false } } }, "required": [ "id", "detail", "delegations", "credentialReadiness", "browserTools", "defaultSuggestedPrompts", "keyModels" ], "additionalProperties": false } }, "required": [ "roster", "apiKeys", "availableApiKeys", "models", "agent" ], "additionalProperties": false } }, "required": [ "conversation", "composer" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/browser-storage-states": { "get": { "operationId": "getBrowserStorageStates", "tags": [ "Browser Storage States" ], "description": "List members whose Playwright browser logins are saved. Returns counts and sizes only, never cookies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:update`](/docs/reference/permissions#member:update): Change member roles and settings", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "nullable": true, "type": "string" }, "siteCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "name", "email", "image", "siteCount", "sizeBytes", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:update" ] } } }, "/api/browser-storage-states/{userId}": { "delete": { "operationId": "deleteBrowserStorageState", "tags": [ "Browser Storage States" ], "description": "Delete a member's saved Playwright browser logins, signing them out of every site in new chats\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:update`](/docs/reference/permissions#member:update): Change member roles and settings", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:update" ] } } }, "/v1/cerebras/chat/completions": { "post": { "operationId": "cerebrasChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Cerebras (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CerebrasChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/cerebras/{agentId}/chat/completions": { "post": { "operationId": "cerebrasChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Cerebras for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CerebrasChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/chat": { "post": { "operationId": "streamChat", "tags": [ "Chat" ], "description": "Stream chat response with MCP tools (useChat format)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "parts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } } }, "required": [ "role", "parts" ], "additionalProperties": {} } }, "trigger": { "type": "string", "enum": [ "submit-message", "regenerate-message" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxSteps": { "type": "integer", "minimum": 1, "maximum": 500 }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "id", "messages" ] } } } }, "responses": { "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/elicitation/{id}": { "post": { "operationId": "resolveChatMcpElicitation", "tags": [ "Chat" ], "description": "Resolve a pending MCP elicitation request from chat\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "enum": [ "accept", "decline", "cancel" ] }, "content": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "conversationId", "action" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/tasks/{taskId}/cancel": { "post": { "operationId": "cancelChatMcpTask", "tags": [ "Chat" ], "description": "Cancel a long-running MCP task started from chat\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "taskId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "boolean" } }, "required": [ "cancelled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/conversations/{id}/stop": { "post": { "operationId": "stopChatStream", "tags": [ "Chat" ], "description": "Stop a running chat stream for a conversation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "stopped": { "type": "boolean" } }, "required": [ "stopped" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/conversations/{id}/active-run": { "get": { "operationId": "getActiveChatRun", "tags": [ "Chat" ], "description": "Reconnect to an active chat stream for a conversation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": {} } } }, "204": { "description": "Default Response" }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/conversations": { "get": { "operationId": "getChatConversations", "tags": [ "Chat" ], "description": "List the current user's conversations with agent details, newest first. Optionally filter by search query. Without a search, `limit` caps the recent conversations returned (pinned ones are always included); search results have their own cap of 50.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "default": 250, "type": "integer", "minimum": 1, "maximum": 250 }, "in": "query", "name": "limit", "required": false, "description": "Recent conversations to return when not searching. Pinned ones are always added." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeArtifacts", "required": false, "description": "Include each chat's artifact and todo list (default true). False returns them as null for lightweight lists." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scheduledRun": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "triggerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "runKind": { "type": "string", "enum": [ "due", "manual" ] }, "scheduleName": { "type": "string" } }, "required": [ "id", "triggerId", "createdAt", "runKind", "scheduleName" ], "additionalProperties": false } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } }, "post": { "operationId": "createChatConversation", "tags": [ "Chat" ], "description": "Create a new conversation with an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:create`](/docs/reference/permissions#chat:create): Start new chat conversations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "encryptedChat": { "type": "boolean" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "agentId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:create" ] } } }, "/api/chat/conversations/deleted": { "get": { "operationId": "getDeletedChatConversations", "tags": [ "Chat" ], "description": "List the current user's soft-deleted conversations (the Trash view), newest deletion first.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:delete`](/docs/reference/permissions#chat:delete): Delete chat conversations", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:delete" ] } } }, "/api/chat/conversations/{id}": { "get": { "operationId": "getChatConversation", "tags": [ "Chat" ], "description": "Get conversation with messages. With `tail`, only the last `tail` messages and the count of the earlier ones (`olderMessageCount`).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "tail", "required": false, "description": "Return only the last N messages" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } }, "patch": { "operationId": "updateChatConversation", "tags": [ "Chat" ], "description": "Update conversation title, model, agent, API key, or project\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "nullable": true, "type": "string" }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } }, "delete": { "operationId": "deleteChatConversation", "tags": [ "Chat" ], "description": "Delete a conversation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:delete`](/docs/reference/permissions#chat:delete): Delete chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:delete" ] } } }, "/api/chat/conversations/{id}/openappa-status": { "get": { "operationId": "getChatOpenappaStatus", "tags": [ "Chat" ], "description": "Get the current OpenAPPA trust and audience of a conversation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "trust": { "type": "string" }, "audience": { "type": "string" }, "policyRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "trust", "audience", "policyRevision" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/conversations/{id}/hooks-debug": { "post": { "operationId": "setConversationHooksDebug", "tags": [ "Chat" ], "description": "Toggle per-conversation hook debug mode (admin only). When on, hook runs surface inline as expandable debug chips for admins.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hooksDebugEnabled": { "type": "boolean" } }, "required": [ "hooksDebugEnabled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/conversations/{id}/read": { "post": { "operationId": "markChatConversationRead", "tags": [ "Chat" ], "description": "Mark a conversation read by its owner, clearing the sidebar new-messages indicator.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/conversations/{id}/files": { "get": { "operationId": "getChatConversationFiles", "tags": [ "Chat" ], "description": "List files for a conversation: this chat's own outputs, user attachments, and — for a project chat — every file in the project (metadata only).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "generated": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "contentUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "mimeType", "contentUrl", "createdAt" ], "additionalProperties": false } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "contentUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "mimeType", "contentUrl", "createdAt" ], "additionalProperties": false } }, "projectFiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "contentUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "mimeType", "contentUrl", "createdAt" ], "additionalProperties": false } }, "projectName": { "nullable": true, "type": "string" }, "canManageFiles": { "type": "boolean" } }, "required": [ "generated", "attachments", "projectFiles", "projectName", "canManageFiles" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/attachments/{id}/content": { "get": { "operationId": "getChatAttachmentContent", "tags": [ "Chat" ], "description": "Stream the bytes of a chat attachment by id. Auth'd to the org.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } } }, "/api/chat/attachments/{id}": { "delete": { "operationId": "deleteChatAttachment", "tags": [ "Chat" ], "description": "Soft-delete a chat attachment by id. Owner-gated: only the conversation owner may remove its attachments.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/conversations/{id}/fork": { "post": { "operationId": "forkChatConversation", "tags": [ "Chat" ], "description": "Create a new conversation from an accessible conversation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:create`](/docs/reference/permissions#chat:create): Start new chat conversations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "agentId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:create" ] } } }, "/api/chat/agents/{agentId}/mcp-tools": { "get": { "operationId": "getChatAgentMcpTools", "tags": [ "Chat" ], "description": "Get MCP tools available for an agent via MCP Gateway\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "description", "parameters", "tokens" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/chat/conversations/{id}/restore": { "post": { "operationId": "restoreChatConversation", "tags": [ "Chat" ], "description": "Restore a soft-deleted conversation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:delete`](/docs/reference/permissions#chat:delete): Delete chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:delete" ] } } }, "/api/chat/conversations/{id}/chat-errors": { "delete": { "operationId": "clearChatConversationErrors", "tags": [ "Chat" ], "description": "Clear a conversation's recorded chat errors\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/conversations/{id}/compact": { "post": { "operationId": "compactChatConversation", "tags": [ "Chat" ], "description": "Compact older chat history for model context\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "created", "existing", "skipped", "failed" ] }, "reason": { "type": "string", "enum": [ "below_threshold", "using_existing_summary", "nothing_to_compact", "missing_boundary_message_id", "not_beneficial", "aborted", "summary_generation_failed" ] }, "compaction": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } }, "required": [ "status", "compaction", "conversation" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/conversations/{id}/generate-title": { "post": { "operationId": "generateChatConversationTitle", "tags": [ "Chat" ], "description": "Generate a title for the conversation based on the first user message and assistant response\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "regenerate": { "description": "Force regeneration even if title already exists (for manual regeneration)", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/messages/{id}": { "patch": { "operationId": "updateChatMessage", "tags": [ "Chat" ], "description": "Update a specific text part in a message\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "partIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string", "minLength": 1 }, "deleteSubsequentMessages": { "type": "boolean" } }, "required": [ "conversationId", "partIndex", "text" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/messages/{id}/feedback": { "patch": { "operationId": "setChatMessageFeedback", "tags": [ "Chat" ], "description": "Set or clear the owner's thumbs feedback on an assistant message\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "feedback": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] } }, "required": [ "conversationId", "feedback" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "feedback": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] } }, "required": [ "id", "feedback" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chat/conversations/{id}/enabled-tools": { "get": { "operationId": "getConversationEnabledTools", "tags": [ "Chat" ], "description": "Get enabled tools for a conversation. Empty array means all profile tools are enabled (default).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:read`](/docs/reference/permissions#chat:read): View and access chat conversations", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasCustomSelection": { "type": "boolean" }, "enabledToolIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "hasCustomSelection", "enabledToolIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:read" ] } }, "put": { "operationId": "updateConversationEnabledTools", "tags": [ "Chat" ], "description": "Set enabled tools for a conversation. Replaces all existing selections.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toolIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "toolIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasCustomSelection": { "type": "boolean" }, "enabledToolIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "hasCustomSelection", "enabledToolIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } }, "delete": { "operationId": "deleteConversationEnabledTools", "tags": [ "Chat" ], "description": "Clear custom tool selection for a conversation (revert to all tools enabled)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`chat:update`](/docs/reference/permissions#chat:update): Edit chat messages and conversation settings", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "chat:update" ] } } }, "/api/chatops/jira/config": { "get": { "operationId": "getJiraChatOpsConfig", "tags": [ "ChatOps" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "siteUrl": { "type": "string" }, "ingressMode": { "type": "string", "enum": [ "hmac", "automation", "poll" ] }, "hasWebhookSecret": { "type": "boolean" }, "webhookUrl": { "nullable": true, "type": "string" }, "bots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "cloudId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "hasApiToken": { "type": "boolean" }, "fallbackServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fallbackReviewerUserId": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "accountId", "displayName", "email", "enabled", "hasApiToken", "fallbackServiceAccountId", "fallbackReviewerUserId" ], "additionalProperties": false } }, "pollingSupported": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "enabled", "siteUrl", "ingressMode", "hasWebhookSecret", "webhookUrl", "bots", "pollingSupported" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels" }, "put": { "operationId": "updateJiraChatOpsConfig", "tags": [ "ChatOps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "siteUrl": { "type": "string", "maxLength": 512 }, "ingressMode": { "type": "string", "enum": [ "hmac", "automation", "poll" ] }, "webhookSecret": { "type": "string", "minLength": 16, "maxLength": 4096 } }, "required": [ "enabled", "siteUrl", "ingressMode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "siteUrl": { "type": "string" }, "ingressMode": { "type": "string", "enum": [ "hmac", "automation", "poll" ] }, "hasWebhookSecret": { "type": "boolean" }, "webhookUrl": { "nullable": true, "type": "string" }, "bots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "cloudId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "hasApiToken": { "type": "boolean" }, "fallbackServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fallbackReviewerUserId": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "accountId", "displayName", "email", "enabled", "hasApiToken", "fallbackServiceAccountId", "fallbackReviewerUserId" ], "additionalProperties": false } }, "pollingSupported": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "enabled", "siteUrl", "ingressMode", "hasWebhookSecret", "webhookUrl", "bots", "pollingSupported" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/chatops/jira/bots": { "post": { "operationId": "createJiraChatOpsBot", "tags": [ "ChatOps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "apiToken": { "type": "string", "minLength": 1, "maxLength": 4096 }, "tokenType": { "default": "classic", "type": "string", "enum": [ "classic", "scoped" ] }, "fallbackServiceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fallbackReviewerUserId": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "agentId", "email", "apiToken" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "cloudId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "hasApiToken": { "type": "boolean" }, "fallbackServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fallbackReviewerUserId": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "accountId", "displayName", "email", "enabled", "hasApiToken", "fallbackServiceAccountId", "fallbackReviewerUserId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/chatops/jira/bots/{botId}": { "patch": { "operationId": "updateJiraChatOpsBot", "tags": [ "ChatOps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fallbackServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fallbackReviewerUserId": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "botId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "accountId": { "type": "string", "minLength": 1, "maxLength": 256 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 256 }, "email": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "cloudId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "hasApiToken": { "type": "boolean" }, "fallbackServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fallbackReviewerUserId": { "nullable": true, "type": "string" } }, "required": [ "id", "agentId", "accountId", "displayName", "email", "enabled", "hasApiToken", "fallbackServiceAccountId", "fallbackReviewerUserId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" }, "delete": { "operationId": "deleteJiraChatOpsBot", "tags": [ "ChatOps" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "botId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/chatops/jira/bots/{botId}/projects": { "get": { "operationId": "listJiraChatOpsProjects", "tags": [ "ChatOps" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "botId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 256 }, "key": { "type": "string", "minLength": 1, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id", "key", "name" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels" } }, "/api/chatops/jira/bots/{botId}/bindings": { "post": { "operationId": "createJiraChatOpsBinding", "tags": [ "ChatOps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "maxLength": 256, "pattern": "^\\d+$" }, "instructions": { "type": "string", "maxLength": 4000 } }, "required": [ "projectId" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "botId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "channelId": { "type": "string", "maxLength": 256 }, "workspaceId": { "nullable": true, "type": "string", "maxLength": 256 }, "channelName": { "nullable": true, "type": "string", "maxLength": 256 }, "workspaceName": { "nullable": true, "type": "string", "maxLength": 256 }, "isDm": { "type": "boolean" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string" }, "dmOwnerEmail": { "nullable": true, "type": "string", "maxLength": 256 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "organizationId", "provider", "channelId", "workspaceId", "channelName", "workspaceName", "isDm", "answerAllMessages", "channelInstructions", "dmOwnerEmail", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/webhooks/chatops/jira/{integrationId}": { "post": { "tags": [ "ChatOps" ], "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "integrationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/webhooks/chatops/ms-teams": { "post": { "tags": [ "ChatOps Webhooks" ], "description": "MS Teams webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/webhooks/chatops/ms-teams/sign-in": { "get": { "tags": [ "ChatOps Webhooks" ], "description": "Start a Teams user's sign-in from a file sign-in card", "parameters": [ { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "key", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/webhooks/chatops/ms-teams/sign-in/callback": { "get": { "tags": [ "ChatOps Webhooks" ], "description": "Finish a Teams user's sign-in for reading group-chat files", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "error", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "error_description", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/webhooks/chatops/slack": { "post": { "tags": [ "ChatOps Webhooks" ], "description": "Slack Events API webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "challenge": { "type": "string" } }, "required": [ "challenge" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/webhooks/chatops/slack/agents/{agentId}": { "post": { "tags": [ "ChatOps Webhooks" ], "description": "Slack Events API webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "challenge": { "type": "string" } }, "required": [ "challenge" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/webhooks/chatops/slack/interactive": { "post": { "tags": [ "ChatOps Webhooks" ], "description": "Slack interactive components endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/webhooks/chatops/slack/agents/{agentId}/interactive": { "post": { "tags": [ "ChatOps Webhooks" ], "description": "Slack interactive components endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/webhooks/chatops/slack/oauth/callback": { "get": { "tags": [ "ChatOps Webhooks" ], "description": "Slack OAuth callback for a Slack bot install", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "error", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/webhooks/chatops/slack/slash-command": { "post": { "tags": [ "ChatOps Webhooks" ], "description": "Slack slash commands endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/chatops/status": { "get": { "operationId": "getChatOpsStatus", "tags": [ "ChatOps" ], "description": "Get chatops provider configuration status\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "displayName": { "type": "string" }, "configured": { "type": "boolean" }, "credentials": { "type": "object", "properties": { "botToken": { "type": "string" }, "appId": { "type": "string" }, "appSecret": { "type": "string" }, "tenantId": { "type": "string" }, "signingSecret": { "type": "string" }, "appLevelToken": { "type": "string" }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] } }, "additionalProperties": false }, "dmInfo": { "type": "object", "properties": { "botUserId": { "type": "string" }, "teamId": { "type": "string" }, "appId": { "type": "string" }, "botUsername": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id", "displayName", "configured" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/chatops/bindings": { "get": { "operationId": "listChatOpsBindings", "tags": [ "ChatOps" ], "description": "List chatops channel bindings with pagination\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "parameters": [ { "schema": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "in": "query", "name": "provider", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "workspaceId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "configured", "unassigned" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "channelName", "createdAt" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "channelId": { "type": "string", "maxLength": 256 }, "workspaceId": { "nullable": true, "type": "string", "maxLength": 256 }, "channelName": { "nullable": true, "type": "string", "maxLength": 256 }, "workspaceName": { "nullable": true, "type": "string", "maxLength": 256 }, "isDm": { "type": "boolean" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string" }, "dmOwnerEmail": { "nullable": true, "type": "string", "maxLength": 256 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "organizationId", "provider", "channelId", "workspaceId", "channelName", "workspaceName", "isDm", "answerAllMessages", "channelInstructions", "dmOwnerEmail", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "counts": { "type": "object", "properties": { "configured": { "type": "number" }, "unassigned": { "type": "number" } }, "required": [ "configured", "unassigned" ], "additionalProperties": false }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "hasDmBinding": { "type": "boolean" }, "workspacesWithUnmentionedTraffic": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "pagination", "counts", "workspaces", "hasDmBinding", "workspacesWithUnmentionedTraffic" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } }, "patch": { "operationId": "bulkUpdateChatOpsBindings", "tags": [ "ChatOps" ], "description": "Bulk-update agent assignment for multiple channel bindings\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expectedAgentAssignments": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "agentId" ] } } }, "required": [ "ids", "agentId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "channelId": { "type": "string", "maxLength": 256 }, "workspaceId": { "nullable": true, "type": "string", "maxLength": 256 }, "channelName": { "nullable": true, "type": "string", "maxLength": 256 }, "workspaceName": { "nullable": true, "type": "string", "maxLength": 256 }, "isDm": { "type": "boolean" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string" }, "dmOwnerEmail": { "nullable": true, "type": "string", "maxLength": 256 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "organizationId", "provider", "channelId", "workspaceId", "channelName", "workspaceName", "isDm", "answerAllMessages", "channelInstructions", "dmOwnerEmail", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/bindings/{id}": { "delete": { "operationId": "deleteChatOpsBinding", "tags": [ "ChatOps" ], "description": "Delete a chatops channel binding\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "patch": { "operationId": "updateChatOpsBinding", "tags": [ "ChatOps" ], "description": "Update a chatops channel binding\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string", "maxLength": 4000 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "channelId": { "type": "string", "maxLength": 256 }, "workspaceId": { "nullable": true, "type": "string", "maxLength": 256 }, "channelName": { "nullable": true, "type": "string", "maxLength": 256 }, "workspaceName": { "nullable": true, "type": "string", "maxLength": 256 }, "isDm": { "type": "boolean" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string" }, "dmOwnerEmail": { "nullable": true, "type": "string", "maxLength": 256 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "organizationId", "provider", "channelId", "workspaceId", "channelName", "workspaceName", "isDm", "answerAllMessages", "channelInstructions", "dmOwnerEmail", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/bindings/dm": { "post": { "operationId": "createChatOpsDmBinding", "tags": [ "ChatOps" ], "description": "Create a pending DM binding so an agent can be pre-assigned before the first DM interaction\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requireNoExistingBinding": { "type": "boolean", "enum": [ true ] } }, "required": [ "provider", "agentId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "channelId": { "type": "string", "maxLength": 256 }, "workspaceId": { "nullable": true, "type": "string", "maxLength": 256 }, "channelName": { "nullable": true, "type": "string", "maxLength": 256 }, "workspaceName": { "nullable": true, "type": "string", "maxLength": 256 }, "isDm": { "type": "boolean" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string" }, "dmOwnerEmail": { "nullable": true, "type": "string", "maxLength": 256 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "organizationId", "provider", "channelId", "workspaceId", "channelName", "workspaceName", "isDm", "answerAllMessages", "channelInstructions", "dmOwnerEmail", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/bindings/assignment-plan": { "post": { "operationId": "applyChatOpsBindingPlan", "tags": [ "ChatOps" ], "description": "Atomically apply ChatOps assignments, channel settings, and pending direct-message bindings for an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetAgentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updates": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string", "maxLength": 4000 }, "bindingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expectedAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "nextAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "bindingId", "expectedAgentId", "nextAgentId" ] } }, "directMessages": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] } }, "required": [ "provider" ] } } }, "required": [ "targetAgentId", "updates", "directMessages" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] }, "channelId": { "type": "string", "maxLength": 256 }, "workspaceId": { "nullable": true, "type": "string", "maxLength": 256 }, "channelName": { "nullable": true, "type": "string", "maxLength": 256 }, "workspaceName": { "nullable": true, "type": "string", "maxLength": 256 }, "isDm": { "type": "boolean" }, "answerAllMessages": { "type": "boolean" }, "channelInstructions": { "nullable": true, "type": "string" }, "dmOwnerEmail": { "nullable": true, "type": "string", "maxLength": 256 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "organizationId", "provider", "channelId", "workspaceId", "channelName", "workspaceName", "isDm", "answerAllMessages", "channelInstructions", "dmOwnerEmail", "agentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read", "organizationSettings:update" ] } } }, "/api/chatops/config/ms-teams": { "get": { "operationId": "getMsTeamsChatOpsConfig", "tags": [ "ChatOps" ], "description": "Get the stored MS Teams chatops configuration without its secrets\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "appId": { "nullable": true, "type": "string" }, "tenantId": { "nullable": true, "type": "string" }, "groupChatFileSignIn": { "type": "boolean" }, "signInRedirectUri": { "type": "string" } }, "required": [ "configured", "updatedAt", "enabled", "appId", "tenantId", "groupChatFileSignIn", "signInRedirectUri" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } }, "put": { "operationId": "updateChatOpsConfigInQuickstart", "tags": [ "ChatOps" ], "description": "Update MS Teams chatops configuration\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "appId": { "type": "string", "minLength": 1, "maxLength": 256 }, "appSecret": { "type": "string", "minLength": 1, "maxLength": 512 }, "tenantId": { "type": "string", "minLength": 1, "maxLength": 256 }, "groupChatFileSignIn": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/ngrok": { "put": { "operationId": "connectNgrok", "tags": [ "ChatOps" ], "description": "Connect an ngrok tunnel for inbound chatops webhooks\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "authToken": { "type": "string", "maxLength": 512 }, "domain": { "type": "string", "maxLength": 256 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" } }, "required": [ "success", "domain" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "delete": { "operationId": "disconnectNgrok", "tags": [ "ChatOps" ], "description": "Stop the ngrok tunnel and clear its credentials\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "get": { "operationId": "getNgrokConfig", "tags": [ "ChatOps" ], "description": "Get saved ngrok configuration (token redacted)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasAuthToken": { "type": "boolean" }, "domain": { "type": "string" } }, "required": [ "hasAuthToken", "domain" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/chatops/config/slack": { "get": { "operationId": "getSlackChatOpsConfig", "tags": [ "ChatOps" ], "description": "Get the stored Slack chatops configuration without its secrets\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "appId": { "nullable": true, "type": "string" }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] } }, "required": [ "configured", "updatedAt", "enabled", "appId", "connectionMode" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } }, "put": { "operationId": "updateSlackChatOpsConfig", "tags": [ "ChatOps" ], "description": "Update Slack chatops configuration\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botToken": { "type": "string", "maxLength": 512 }, "signingSecret": { "type": "string", "maxLength": 256 }, "appId": { "type": "string", "maxLength": 256 }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] }, "appLevelToken": { "type": "string", "maxLength": 512 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/agents": { "get": { "operationId": "listSlackAgentBots", "tags": [ "ChatOps" ], "description": "List the Slack bots that each answer as one agent, with their connection status\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "bots": { "type": "array", "items": { "type": "object", "properties": { "identitySyncError": { "nullable": true, "type": "string" }, "handle": { "nullable": true, "type": "string" }, "missingScopes": { "type": "array", "items": { "type": "string" } }, "reinstallUrl": { "nullable": true, "type": "string" }, "installed": { "type": "boolean" }, "needsAppLevelToken": { "type": "boolean" }, "createdByArchestra": { "type": "boolean" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "agentId": { "type": "string" }, "agentName": { "type": "string" }, "enabled": { "type": "boolean" }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] }, "appId": { "type": "string" }, "connected": { "type": "boolean" }, "botUserId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" } }, "required": [ "identitySyncError", "handle", "missingScopes", "reinstallUrl", "installed", "needsAppLevelToken", "createdByArchestra", "createdBy", "agentId", "agentName", "enabled", "connectionMode", "appId", "connected", "botUserId", "teamId" ], "additionalProperties": false } }, "canCreateApps": { "type": "boolean" }, "oneClickInstall": { "type": "boolean" }, "workspaceName": { "nullable": true, "type": "string" }, "unassignedApp": { "nullable": true, "type": "object", "properties": { "appId": { "type": "string" }, "handle": { "nullable": true, "type": "string" }, "connected": { "type": "boolean" }, "installed": { "type": "boolean" }, "needsAppLevelToken": { "type": "boolean" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] }, "agentUsage": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "agentName": { "type": "string" }, "bindings": { "type": "number" } }, "required": [ "agentId", "agentName", "bindings" ], "additionalProperties": false } } }, "required": [ "appId", "handle", "connected", "installed", "needsAppLevelToken", "createdBy", "connectionMode", "agentUsage" ], "additionalProperties": false } }, "required": [ "bots", "canCreateApps", "oneClickInstall", "workspaceName", "unassignedApp" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/chatops/config/slack/convert-app": { "post": { "operationId": "convertSlackAppToAgentBot", "tags": [ "ChatOps" ], "description": "Turn the channel-routed Slack app into the Slack bot of one agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "agentId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "reinstallUrl": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/agents/{agentId}": { "put": { "operationId": "updateSlackAgentBot", "tags": [ "ChatOps" ], "description": "Connect a Slack app whose bot always answers as this agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botToken": { "type": "string", "maxLength": 512 }, "signingSecret": { "type": "string", "maxLength": 256 }, "appId": { "type": "string", "maxLength": 256 }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] }, "appLevelToken": { "type": "string", "maxLength": 512 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "delete": { "operationId": "deleteSlackAgentBot", "tags": [ "ChatOps" ], "description": "Disconnect the Slack bot pinned to this agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/app-config-token": { "put": { "operationId": "updateSlackAppConfigToken", "tags": [ "ChatOps" ], "description": "Save your Slack app configuration token, used to create and update Slack apps for you\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "minLength": 1, "maxLength": 512 }, "refreshToken": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "accessToken", "refreshToken" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "migrated": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "agentId": { "type": "string" }, "ok": { "type": "boolean" }, "error": { "type": "string" }, "reinstallUrl": { "type": "string" } }, "required": [ "appId", "ok" ], "additionalProperties": false } } }, "required": [ "success", "migrated" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/apps/migrate": { "post": { "operationId": "migrateSlackApps", "tags": [ "ChatOps" ], "description": "Update every connected Slack app to the current settings (agent experience, events, scopes)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "migrated": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "agentId": { "type": "string" }, "ok": { "type": "boolean" }, "error": { "type": "string" }, "reinstallUrl": { "type": "string" } }, "required": [ "appId", "ok" ], "additionalProperties": false } } }, "required": [ "migrated" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/agents/{agentId}/app": { "post": { "operationId": "createSlackAgentBotApp", "tags": [ "ChatOps" ], "description": "Create a Slack app for this agent's bot and return its install link\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,34}$" }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] } }, "required": [ "appName", "connectionMode" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "installUrl": { "type": "string" }, "installMode": { "type": "string", "enum": [ "oauth", "manual" ] } }, "required": [ "appId", "installUrl", "installMode" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/router/app": { "post": { "operationId": "createSlackRouterBotApp", "tags": [ "ChatOps" ], "description": "Create the Slack app of the router bot and return its install link\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,34}$" }, "connectionMode": { "type": "string", "enum": [ "webhook", "socket" ] } }, "required": [ "appName", "connectionMode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "installUrl": { "type": "string" }, "installMode": { "type": "string", "enum": [ "oauth", "manual" ] } }, "required": [ "appId", "installUrl", "installMode" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/agents/{agentId}/channels": { "get": { "operationId": "listSlackAgentBotChannels", "tags": [ "ChatOps" ], "description": "List the Slack channels an agent's bot is in or can join\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "nullable": true, "type": "string" }, "canJoin": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string" }, "channelName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "isPrivate": { "type": "boolean" }, "isMember": { "type": "boolean" } }, "required": [ "channelId", "channelName", "description", "isPrivate", "isMember" ], "additionalProperties": false } } }, "required": [ "workspaceId", "canJoin", "channels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/chatops/config/slack/agents/{agentId}/channels/{channelId}/join": { "post": { "operationId": "joinSlackAgentBotChannel", "tags": [ "ChatOps" ], "description": "Add an agent's Slack bot to a public channel\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "pattern": "^[A-Z0-9]+$" }, "in": "path", "name": "channelId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/slack/router/channels": { "get": { "operationId": "listSlackRouterBotChannels", "tags": [ "ChatOps" ], "description": "List the Slack channels the router bot is in or can join\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "nullable": true, "type": "string" }, "canJoin": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "channelId": { "type": "string" }, "channelName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "isPrivate": { "type": "boolean" }, "isMember": { "type": "boolean" } }, "required": [ "channelId", "channelName", "description", "isPrivate", "isMember" ], "additionalProperties": false } } }, "required": [ "workspaceId", "canJoin", "channels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/chatops/config/slack/router/channels/{channelId}/join": { "post": { "operationId": "joinSlackRouterBotChannel", "tags": [ "ChatOps" ], "description": "Add the Slack router bot to a public channel\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Z0-9]+$" }, "in": "path", "name": "channelId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/config/telegram": { "get": { "operationId": "getTelegramChatOpsConfig", "tags": [ "ChatOps" ], "description": "Get the stored Telegram chatops configuration without its bot token\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" } }, "required": [ "configured", "updatedAt", "enabled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } }, "put": { "operationId": "updateTelegramChatOpsConfig", "tags": [ "ChatOps" ], "description": "Update Telegram chatops configuration\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botToken": { "type": "string", "maxLength": 256 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/chatops/telegram/link-code": { "post": { "operationId": "generateTelegramLinkCode", "tags": [ "ChatOps" ], "description": "Generate a one-shot code that links the current user's Telegram account via a t.me deep link\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "botUsername": { "type": "string" } }, "required": [ "code", "botUsername" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/chatops/telegram/link": { "post": { "operationId": "linkTelegramChatOpsAccount", "tags": [ "ChatOps" ], "description": "Link the current user's Telegram account using a code from the bot\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "unlinkTelegramChatOpsAccount", "tags": [ "ChatOps" ], "description": "Unlink the current user's Telegram account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/chatops/channel-discovery/refresh": { "post": { "operationId": "refreshChatOpsChannelDiscovery", "tags": [ "ChatOps" ], "description": "Refresh channel discovery cache for a chatops provider\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ms-teams", "slack", "telegram", "jira" ] } }, "required": [ "provider" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/client-connections/installer": { "get": { "operationId": "getClientConnectionInstaller", "tags": [ "Connection Setups" ], "description": "Public, credential-free Node.js client connection installer.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/client-connections": { "post": { "operationId": "startClientConnection", "tags": [ "Connection Setups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "enum": [ "claude-code", "cursor", "codex", "chatgpt", "claude-desktop", "copilot-cli", "opencode", "kilo", "pi", "kimi-code", "grok-build" ] }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "exclude": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "tools", "skills", "proxy", "plugins" ] } }, "gateway": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" }, "plugins": { "maxItems": 555, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" } }, "deviceName": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "clientId", "platform" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deviceCode": { "type": "string" }, "userCode": { "type": "string" }, "verificationPath": { "type": "string" }, "expiresAt": { "type": "string" }, "interval": { "type": "number" } }, "required": [ "id", "deviceCode", "userCode", "verificationPath", "expiresAt", "interval" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/client-connections/poll": { "post": { "operationId": "pollClientConnection", "tags": [ "Connection Setups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/client-connections/{id}": { "get": { "operationId": "getClientConnection", "tags": [ "Connection Setups" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "enum": [ "claude-code", "cursor", "codex", "chatgpt", "claude-desktop", "copilot-cli", "opencode", "kilo", "pi", "kimi-code", "grok-build" ] }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "exclude": { "type": "array", "items": { "type": "string", "enum": [ "tools", "skills", "proxy", "plugins" ] } }, "gateway": { "nullable": true, "type": "string" }, "plugins": { "nullable": true, "type": "array", "items": { "type": "string" } }, "deviceName": { "nullable": true, "type": "string" }, "userCode": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "clientId", "platform", "exclude", "gateway", "plugins", "deviceName", "userCode", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/client-connections/{id}/decision": { "post": { "operationId": "decideClientConnection", "tags": [ "Connection Setups" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve" ] }, "setupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "decision", "setupId" ] }, { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "deny" ] } }, "required": [ "decision" ] } ] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "denied" ] }, "clientId": { "type": "string", "enum": [ "claude-code", "cursor", "codex", "chatgpt", "claude-desktop", "copilot-cli", "opencode", "kilo", "pi", "kimi-code", "grok-build" ] }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] } }, "required": [ "status", "clientId", "platform" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/v1/cohere/chat": { "post": { "operationId": "cohereChatWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Send a chat request to Cohere using the default agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for API auth" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/cohere/{agentId}/chat": { "post": { "operationId": "cohereChatWithAgent", "tags": [ "LLM Proxy" ], "description": "Send a chat request to Cohere using a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for API auth" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohereChatResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/config/public": { "get": { "operationId": "getPublicConfig", "tags": [ "Config" ], "description": "Get public config\n\nAuthentication:\n\nNot required.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "disableBasicAuth": { "type": "boolean" }, "disableInvitations": { "type": "boolean" }, "disableImpersonation": { "type": "boolean" }, "devAutoLoginEnabled": { "type": "boolean" }, "maintenanceMode": { "nullable": true, "type": "string" }, "siteNotificationMessage": { "nullable": true, "type": "string" }, "enterpriseCoreActive": { "type": "boolean" }, "analytics": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "instanceId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "posthog": { "type": "object", "properties": { "key": { "type": "string" }, "host": { "type": "string" } }, "required": [ "key", "host" ], "additionalProperties": false } }, "required": [ "enabled", "instanceId", "posthog" ], "additionalProperties": false }, "rum": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "sampleRate": { "type": "number" } }, "required": [ "enabled", "sampleRate" ], "additionalProperties": false } }, "required": [ "disableBasicAuth", "disableInvitations", "disableImpersonation", "devAutoLoginEnabled", "maintenanceMode", "siteNotificationMessage", "enterpriseCoreActive", "analytics", "rum" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/config": { "get": { "operationId": "getConfig", "tags": [ "Config" ], "description": "Get platform configuration and feature flags\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "enterpriseFeatures": { "type": "object", "properties": { "core": { "type": "boolean" }, "knowledgeBase": { "type": "boolean" }, "fullWhiteLabeling": { "type": "boolean" } }, "required": [ "core", "knowledgeBase", "fullWhiteLabeling" ], "additionalProperties": false }, "smallTeamTier": { "type": "object", "properties": { "threshold": { "type": "number" }, "userCount": { "type": "number" }, "smallTeam": { "type": "boolean" }, "envFlag": { "type": "boolean" }, "communicate": { "type": "boolean" } }, "required": [ "threshold", "userCount", "smallTeam", "envFlag", "communicate" ], "additionalProperties": false }, "features": { "type": "object", "properties": { "orchestratorK8sRuntime": { "type": "boolean" }, "agentIdentitySpiffe": { "type": "object", "properties": { "trustDomain": { "type": "string" }, "issuer": { "type": "string" }, "jwksUri": { "type": "string" }, "bundleUri": { "type": "string" } }, "required": [ "trustDomain", "issuer", "jwksUri", "bundleUri" ], "additionalProperties": false }, "mcpIdleHibernationBetaEnabled": { "deprecated": true, "description": "Deprecated. Always true: MCP idle hibernation is generally available. Kept for backward compatibility.", "type": "boolean" }, "sandbox": { "type": "boolean" }, "agentRuntime": { "type": "boolean" }, "agentRuntimeCatalogImages": { "type": "object", "additionalProperties": { "type": "string" } }, "agentRuntimeBackend": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "kubernetes" ] }, "available": { "type": "boolean" }, "defaultTtlHours": { "type": "number" }, "defaultIdleTimeoutMinutes": { "type": "number" }, "allowPrivileged": { "type": "boolean" } }, "required": [ "name", "available", "defaultTtlHours", "defaultIdleTimeoutMinutes", "allowPrivileged" ], "additionalProperties": false }, "plugins": { "type": "boolean" }, "sandboxArtifactBytesLimit": { "type": "number" }, "chatAttachmentStorageBytesLimit": { "type": "number" }, "apiBodyLimitBytes": { "type": "number" }, "azureOpenAiEntraIdEnabled": { "type": "boolean" }, "anthropicWifEnabled": { "type": "boolean" }, "anthropicKeylessAuthEnabled": { "type": "boolean" }, "anthropicVertexAiEnabled": { "type": "boolean" }, "bedrockIamAuthEnabled": { "type": "boolean" }, "geminiVertexAiEnabled": { "type": "boolean" }, "incomingEmail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "outlook" ] }, "displayName": { "type": "string" }, "emailDomain": { "type": "string" } }, "required": [ "enabled" ], "additionalProperties": false }, "mcpServerBaseImage": { "type": "string" }, "orchestratorK8sNamespace": { "type": "string" }, "environmentNamespaces": { "type": "array", "items": { "type": "string" } }, "isQuickstart": { "type": "boolean" }, "ngrokDomain": { "type": "string" }, "virtualKeyDefaultExpirationSeconds": { "type": "number" }, "mcpSandboxDomain": { "nullable": true, "type": "string" }, "maintenanceMode": { "nullable": true, "type": "string" }, "chatSecretScanEnabled": { "type": "boolean" }, "encryptedChatEnabled": { "type": "boolean" }, "openappaEnabled": { "type": "boolean" }, "agentHooksEnabled": { "type": "boolean" }, "chatopsTelegramEnabled": { "type": "boolean" }, "kbMfilesConnectorEnabled": { "type": "boolean" }, "kbMfilesOauthEnabled": { "type": "boolean" }, "kbBm25DefaultK1": { "type": "number" }, "kbBm25DefaultB": { "type": "number" }, "kbContextualRetrievalDefaultMode": { "$ref": "#/components/schemas/ContextualRetrievalMode" }, "kbGoogleDriveOAuth": { "type": "object", "properties": { "configured": { "type": "boolean" }, "redirectUri": { "type": "string" } }, "required": [ "configured", "redirectUri" ], "additionalProperties": false }, "devFeedbackEnabled": { "type": "boolean" } }, "required": [ "orchestratorK8sRuntime", "agentIdentitySpiffe", "sandbox", "agentRuntime", "agentRuntimeCatalogImages", "agentRuntimeBackend", "plugins", "sandboxArtifactBytesLimit", "chatAttachmentStorageBytesLimit", "apiBodyLimitBytes", "azureOpenAiEntraIdEnabled", "anthropicWifEnabled", "anthropicKeylessAuthEnabled", "anthropicVertexAiEnabled", "bedrockIamAuthEnabled", "geminiVertexAiEnabled", "incomingEmail", "mcpServerBaseImage", "orchestratorK8sNamespace", "environmentNamespaces", "isQuickstart", "ngrokDomain", "virtualKeyDefaultExpirationSeconds", "mcpSandboxDomain", "maintenanceMode", "chatSecretScanEnabled", "encryptedChatEnabled", "openappaEnabled", "agentHooksEnabled", "chatopsTelegramEnabled", "kbMfilesConnectorEnabled", "kbMfilesOauthEnabled", "kbBm25DefaultK1", "kbBm25DefaultB", "kbContextualRetrievalDefaultMode", "kbGoogleDriveOAuth", "devFeedbackEnabled" ], "additionalProperties": false }, "providerBaseUrls": { "type": "object", "additionalProperties": { "nullable": true, "type": "string" }, "required": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] } }, "required": [ "version", "enterpriseFeatures", "smallTeamTier", "features", "providerBaseUrls" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connected-clients": { "get": { "operationId": "getConnectedClients", "tags": [ "Connection Setups" ], "description": "List the coding clients the signed-in user connected through the Connect page, from their redeemed setup tickets and, for clients the gateway can tell apart, their gateway sign-in.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 2048 }, "name": { "type": "string" }, "lastConnectedAt": { "type": "string", "format": "date-time" }, "deviceNames": { "type": "array", "items": { "type": "string" } }, "lastSeenAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "clientId", "name", "lastConnectedAt", "deviceNames", "lastSeenAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connected-clients/log": { "get": { "operationId": "getConnectedClientLog", "tags": [ "Connection Setups" ], "description": "Log of the organization's agent connections, newest first: an event each time a member connected a coding client through the Connect page, with the machine and what the setup included, each time one was disconnected, and each agent's first OAuth sign-in to the gateway under the name it registered.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:admin`](/docs/reference/permissions#log:admin): View every LLM, MCP, and Guardrails consult log in your organization (also requires Read)\n[`member:read`](/docs/reference/permissions#member:read): View organization members and their roles", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "userId", "required": false, "description": "Only events for this user's clients" }, { "schema": { "type": "string", "enum": [ "connected", "disconnected" ] }, "in": "query", "name": "action", "required": false, "description": "Only connects or only disconnects" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Events on or after this date (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Events on or before this date (ISO 8601)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "connected", "disconnected" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "userId": { "type": "string" }, "userName": { "type": "string" }, "userEmail": { "type": "string" }, "clientId": { "nullable": true, "type": "string" }, "agentName": { "type": "string" }, "via": { "type": "string", "enum": [ "setup", "oauthSignIn" ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "macos", "linux", "windows" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "deviceName": { "nullable": true, "type": "string" }, "mcpGateway": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "llmProxy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "includeSkills": { "type": "boolean" }, "skillCount": { "type": "number" }, "disconnectedBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "action", "occurredAt", "userId", "userName", "userEmail", "clientId", "agentName", "via", "platform", "deviceName", "mcpGateway", "llmProxy", "includeSkills", "skillCount", "disconnectedBy" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:admin", "member:read" ] } } }, "/api/connected-clients/adoption": { "get": { "operationId": "getAgentAdoption", "tags": [ "Connection Setups" ], "description": "Every organization member with their agents (set up through the Connect page, signed in to the gateway, or seen calling it or the LLM proxy) and the last MCP gateway and LLM proxy use seen from them. A member is active when their agents made gateway or LLM proxy calls in the window (the last 30 days unless picked); setups and sign-ins alone only show the installer ran.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:admin`](/docs/reference/permissions#log:admin): View every LLM, MCP, and Guardrails consult log in your organization (also requires Read)\n[`member:read`](/docs/reference/permissions#member:read): View organization members and their roles", "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Traffic on or after this date (ISO 8601); the last 30 days when left out" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Traffic on or before this date (ISO 8601); now when left out" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "notConnected" ] }, "gatewayLastSeenAt": { "nullable": true, "type": "string", "format": "date-time" }, "llmLastSeenAt": { "nullable": true, "type": "string", "format": "date-time" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "notConnected" ] }, "setupAt": { "nullable": true, "type": "string", "format": "date-time" }, "signedIn": { "type": "boolean" }, "viaToken": { "type": "boolean" }, "lastGatewayCallAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastLlmCallAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "clientId", "name", "status", "setupAt", "signedIn", "viaToken", "lastGatewayCallAt", "lastLlmCallAt" ], "additionalProperties": false } }, "gatewayUses": { "type": "array", "items": { "type": "object", "properties": { "via": { "type": "object", "properties": { "id": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "agent": { "type": "object", "properties": { "clientId": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "clientId", "name" ], "additionalProperties": false }, "calls": { "type": "number" }, "lastSeenAt": { "type": "string", "format": "date-time" } }, "required": [ "via", "agent", "calls", "lastSeenAt" ], "additionalProperties": false } }, "llmUses": { "type": "array", "items": { "type": "object", "properties": { "via": { "type": "object", "properties": { "id": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "agent": { "type": "object", "properties": { "clientId": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "clientId", "name" ], "additionalProperties": false }, "calls": { "type": "number" }, "lastSeenAt": { "type": "string", "format": "date-time" } }, "required": [ "via", "agent", "calls", "lastSeenAt" ], "additionalProperties": false } } }, "required": [ "userId", "name", "email", "status", "gatewayLastSeenAt", "llmLastSeenAt", "agents", "gatewayUses", "llmUses" ], "additionalProperties": false } } }, "required": [ "since", "until", "members" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:admin", "member:read" ] } } }, "/api/connected-clients/adoption/usage": { "get": { "operationId": "getAgentAdoptionUsage", "tags": [ "Connection Setups" ], "description": "MCP gateway and LLM proxy calls from members' agents per UTC day over the window (the last 30 days unless picked), for one member or the whole organization. Counts the same traffic as the adoption summary.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:admin`](/docs/reference/permissions#log:admin): View every LLM, MCP, and Guardrails consult log in your organization (also requires Read)\n[`member:read`](/docs/reference/permissions#member:read): View organization members and their roles", "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Traffic on or after this date (ISO 8601); the last 30 days when left out" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Traffic on or before this date (ISO 8601); now when left out" }, { "schema": { "type": "string" }, "in": "query", "name": "userId", "required": false, "description": "Only this member's calls; the whole organization when left out" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "gatewayCalls": { "type": "number" }, "llmCalls": { "type": "number" } }, "required": [ "date", "gatewayCalls", "llmCalls" ], "additionalProperties": false } } }, "required": [ "since", "until", "days" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:admin", "member:read" ] } } }, "/api/connected-clients/{clientId}": { "delete": { "operationId": "disconnectConnectedClient", "tags": [ "Connection Setups" ], "description": "Disconnect one of the signed-in user's coding clients: it leaves the connected list and the skill share links its setups created are revoked. Where the gateway can tell the client apart by its OAuth client (Claude Code, Amp), the user's tokens and consent for it are deleted too; other clients keep their gateway sign-in until it expires. Local client configuration is removed separately by /disconnect.md.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "in": "path", "name": "clientId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connection-setups/startup-guard": { "post": { "operationId": "renderStartupGuard", "tags": [ "Connection Setups" ], "description": "Render a credential-free startup check without replaying connection setup.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "enum": [ "claude-code", "codex", "copilot-cli", "opencode", "kilo", "kimi-code" ] }, "platform": { "type": "string", "enum": [ "bash", "windows" ] }, "context": { "type": "object", "properties": { "appName": { "type": "string", "maxLength": 512 }, "healthUrl": { "nullable": true, "type": "string", "maxLength": 2048, "format": "uri" }, "mcp": { "nullable": true, "type": "object", "properties": { "serverName": { "type": "string", "maxLength": 512 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "ref": { "nullable": true, "type": "string", "maxLength": 512 } }, "required": [ "serverName", "url", "ref" ], "additionalProperties": false }, "proxy": { "nullable": true, "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string", "maxLength": 512 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "ref": { "nullable": true, "type": "string", "maxLength": 512 }, "proxyName": { "type": "string", "maxLength": 512 }, "authMode": { "type": "string", "enum": [ "provider-key", "virtual-key", "primary-providers" ] }, "usesModelCatalog": { "type": "boolean" }, "passthroughVirtualKey": { "nullable": true, "type": "string", "enum": [ "ARCH_GUARD_PRIVATE_KEY" ] } }, "required": [ "provider", "providerLabel", "url", "ref", "proxyName" ], "additionalProperties": false }, "skills": { "nullable": true, "type": "object", "properties": { "marketplaceName": { "type": "string", "maxLength": 512 }, "cloneUrl": { "type": "string", "enum": [ "ARCH_GUARD_PRIVATE_CLONE_URL" ] }, "hasSkills": { "type": "boolean" }, "connectionPlugin": { "type": "boolean" }, "pluginNames": { "maxItems": 555, "type": "array", "items": { "type": "string", "maxLength": 512 } } }, "required": [ "marketplaceName", "cloneUrl" ], "additionalProperties": false } }, "required": [ "appName", "healthUrl", "mcp", "proxy", "skills" ], "additionalProperties": false } }, "required": [ "clientId", "platform", "context" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "number", "enum": [ 1 ] }, "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clientId": { "type": "string", "enum": [ "claude-code", "codex", "copilot-cli", "opencode", "kilo", "kimi-code" ] }, "platform": { "type": "string", "enum": [ "bash", "windows" ] }, "source": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "format", "version", "clientId", "platform", "source", "sha256" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connection-setups/runtime": { "get": { "operationId": "getConnectionRuntime", "tags": [ "Connection Setups" ], "description": "Read executable managed launcher/plugin artifacts using a distinct installation update capability. Consumed connection, revocation, live membership and resource access are rechecked. Does not replay installation or issue credentials.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "number", "enum": [ 1 ] }, "installation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "clientId": { "type": "string", "enum": [ "opencode", "kilo" ] }, "artifacts": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "source", "sha256" ], "additionalProperties": false } } }, "required": [ "format", "installation", "clientId", "artifacts" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/connection-instructions": { "get": { "operationId": "getConnectionInstructions", "tags": [ "Connection Setups" ], "description": "Read current managed instructions with an installation-scoped read-only credential. Live membership and gateway access are rechecked.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "nullable": true, "type": "string", "maxLength": 20000 }, "version": { "type": "string" } }, "required": [ "instructions", "version" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/health": { "get": { "operationId": "getConnectionHealth", "tags": [ "Connection Setups" ], "description": "Health of the remotes a connected client is wired to, one request for all of them. Public: used by the Claude Code startup guard before every launch, from machines with no session. Reports only ok/down per requested remote, the launch check's format version, and the gateway's tool prefix.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "in": "query", "name": "mcp", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "in": "query", "name": "llm", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp": { "type": "string", "enum": [ "ok", "down" ] }, "llm": { "type": "string", "enum": [ "ok", "down" ] }, "guardVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mcpToolPrefix": { "type": "string" } }, "required": [ "guardVersion", "mcpToolPrefix" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/connection-setups": { "post": { "operationId": "createConnectionSetup", "tags": [ "Connection Setups" ], "description": "Persist /connection wizard selections and return a one-time `curl | bash` command. The command's setup token is shown exactly once and expires after 15 minutes.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "enum": [ "claude-code", "cursor", "codex", "chatgpt", "claude-desktop", "copilot-cli", "opencode", "kilo", "pi", "kimi-code", "grok-build" ] }, "platform": { "default": "macos", "type": "string", "enum": [ "macos", "linux", "windows" ] }, "baseUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "mcpGatewayId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmProxyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "proxyAuth": { "type": "string", "enum": [ "native-session", "provider-key", "virtual-key", "primary-providers" ] }, "attributePassthrough": { "default": true, "type": "boolean" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "model": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x20-\\x7E]+$" }, "skills": { "type": "object", "properties": { "skillIds": { "minItems": 1, "maxItems": 1111, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "ttlDays": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 3650 } }, "required": [ "skillIds", "ttlDays" ] }, "pluginIds": { "maxItems": 555, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "clientId", "baseUrl" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "command": { "type": "string" }, "installerUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "tokenStart": { "type": "string" }, "creditWarning": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "insufficient_balance", "unverified" ] }, "keyName": { "type": "string" } }, "required": [ "kind", "keyName" ], "additionalProperties": false }, "plugins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "clientType": { "type": "string", "enum": [ "claude-code", "cursor", "codex", "chatgpt", "claude-desktop", "copilot-cli", "opencode", "kilo", "pi", "kimi-code", "grok-build" ] } }, "required": [ "id", "pluginSlug", "displayName", "clientType" ], "additionalProperties": false } } }, "required": [ "id", "command", "expiresAt", "tokenStart", "plugins" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connection-setups/virtual-key": { "post": { "operationId": "createConnectionVirtualKey", "tags": [ "Connection Setups" ], "description": "Provision (or reuse) the caller's personal connection virtual key for a provider and return its value once. Backs the manual /connection flow's virtual-key option; mirrors the auto-provisioning done by the one-command setup. Requires llmVirtualKey:create.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] } }, "required": [ "provider" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "name": { "type": "string" }, "creditWarning": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "insufficient_balance", "unverified" ] }, "keyName": { "type": "string" } }, "required": [ "kind", "keyName" ], "additionalProperties": false } }, "required": [ "value", "name" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connection-setups/passthrough-key": { "post": { "operationId": "createConnectionPassthroughKey", "tags": [ "Connection Setups" ], "description": "Provision (or reuse) the caller's personal passthrough virtual key scoped to an LLM proxy and return its value once. Backs the manual /connection flow's X-Archestra-Virtual-Key attribution step for Claude Code and Claude Desktop. Requires llmVirtualKey:create.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "llmProxyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "llmProxyId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "name": { "type": "string" } }, "required": [ "value", "name" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/connection-setups/script/{token}": { "get": { "operationId": "getConnectionSetupScript", "tags": [ "Connection Setups" ], "description": "Serve the rendered one-time setup script for a connection setup. Authenticates via the one-time token in the path; the token is consumed atomically on the first successful render.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "desktop" ] }, "in": "query", "name": "download", "required": false }, { "schema": { "type": "string", "minLength": 20, "maxLength": 256 }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/cost-exports": { "get": { "operationId": "listCostExports", "tags": [ "Cost Exports" ], "description": "List the organization's scheduled cost exports.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`costExport:read`](/docs/reference/permissions#costExport:read): View scheduled cost exports and their run status", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "blobProviderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 256 }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "focus_csv" ] }, "schedule": { "type": "string", "enum": [ "hourly", "daily" ] }, "pathPrefix": { "type": "string", "maxLength": 512 }, "exportedThrough": { "type": "string", "format": "date-time" }, "lastRunAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastRunStatus": { "nullable": true, "type": "string", "enum": [ "success", "failed" ] }, "lastRunError": { "nullable": true, "type": "string" }, "lastObjectKey": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "blobProviderName": { "type": "string" }, "running": { "type": "boolean", "description": "Whether a run is queued or in progress right now." }, "nextRetryAt": { "nullable": true, "description": "When a failing export is next retried; retries back off from 5 minutes to an hour. Null unless the last run failed.", "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "blobProviderId", "name", "enabled", "format", "schedule", "pathPrefix", "exportedThrough", "lastRunAt", "lastRunStatus", "lastRunError", "lastObjectKey", "createdAt", "updatedAt", "blobProviderName", "running", "nextRetryAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "costExport:read" ] } }, "post": { "operationId": "createCostExport", "tags": [ "Cost Exports" ], "description": "Schedule an export of LLM cost and usage to a blob provider. The first file covers the period in progress, once it completes.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`costExport:create`](/docs/reference/permissions#costExport:create): Schedule cost exports to a blob provider\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "blobProviderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "format": { "default": "focus_csv", "type": "string", "enum": [ "focus_csv" ] }, "schedule": { "default": "daily", "type": "string", "enum": [ "hourly", "daily" ] }, "pathPrefix": { "description": "Key prefix for the export's files, under the blob provider's own prefix.", "type": "string", "maxLength": 512 }, "enabled": { "default": true, "type": "boolean" }, "startFrom": { "description": "Export usage from this time on, including the past (a backfill). Defaults to now: the first file is the period in progress.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "name", "blobProviderId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "blobProviderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 256 }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "focus_csv" ] }, "schedule": { "type": "string", "enum": [ "hourly", "daily" ] }, "pathPrefix": { "type": "string", "maxLength": 512 }, "exportedThrough": { "type": "string", "format": "date-time" }, "lastRunAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastRunStatus": { "nullable": true, "type": "string", "enum": [ "success", "failed" ] }, "lastRunError": { "nullable": true, "type": "string" }, "lastObjectKey": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "blobProviderName": { "type": "string" }, "running": { "type": "boolean", "description": "Whether a run is queued or in progress right now." }, "nextRetryAt": { "nullable": true, "description": "When a failing export is next retried; retries back off from 5 minutes to an hour. Null unless the last run failed.", "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "blobProviderId", "name", "enabled", "format", "schedule", "pathPrefix", "exportedThrough", "lastRunAt", "lastRunStatus", "lastRunError", "lastObjectKey", "createdAt", "updatedAt", "blobProviderName", "running", "nextRetryAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "costExport:create", "llmCost:read" ] } } }, "/api/cost-exports/{id}": { "put": { "operationId": "updateCostExport", "tags": [ "Cost Exports" ], "description": "Update a scheduled cost export.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`costExport:update`](/docs/reference/permissions#costExport:update): Change, pause, resume, and run cost exports\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "blobProviderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "format": { "type": "string", "enum": [ "focus_csv" ] }, "schedule": { "type": "string", "enum": [ "hourly", "daily" ] }, "pathPrefix": { "description": "Key prefix for the export's files, under the blob provider's own prefix.", "type": "string", "maxLength": 512 }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "blobProviderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 256 }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "focus_csv" ] }, "schedule": { "type": "string", "enum": [ "hourly", "daily" ] }, "pathPrefix": { "type": "string", "maxLength": 512 }, "exportedThrough": { "type": "string", "format": "date-time" }, "lastRunAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastRunStatus": { "nullable": true, "type": "string", "enum": [ "success", "failed" ] }, "lastRunError": { "nullable": true, "type": "string" }, "lastObjectKey": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "blobProviderName": { "type": "string" }, "running": { "type": "boolean", "description": "Whether a run is queued or in progress right now." }, "nextRetryAt": { "nullable": true, "description": "When a failing export is next retried; retries back off from 5 minutes to an hour. Null unless the last run failed.", "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "blobProviderId", "name", "enabled", "format", "schedule", "pathPrefix", "exportedThrough", "lastRunAt", "lastRunStatus", "lastRunError", "lastObjectKey", "createdAt", "updatedAt", "blobProviderName", "running", "nextRetryAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "costExport:update", "llmCost:read" ] } }, "delete": { "operationId": "deleteCostExport", "tags": [ "Cost Exports" ], "description": "Delete a scheduled cost export. Files already written stay in the bucket.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`costExport:delete`](/docs/reference/permissions#costExport:delete): Delete cost exports", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "costExport:delete" ] } } }, "/api/cost-exports/{id}/run": { "post": { "operationId": "runCostExport", "tags": [ "Cost Exports" ], "description": "Queue a run of a cost export now: it writes every completed period not exported yet, or rewrites the most recent completed period when none is due. Returns 202 with the export (`running: true`); the outcome lands in its `lastRun*` fields. 409 when a run is already queued or in progress.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`costExport:update`](/docs/reference/permissions#costExport:update): Change, pause, resume, and run cost exports\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "blobProviderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 256 }, "enabled": { "type": "boolean" }, "format": { "type": "string", "enum": [ "focus_csv" ] }, "schedule": { "type": "string", "enum": [ "hourly", "daily" ] }, "pathPrefix": { "type": "string", "maxLength": 512 }, "exportedThrough": { "type": "string", "format": "date-time" }, "lastRunAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastRunStatus": { "nullable": true, "type": "string", "enum": [ "success", "failed" ] }, "lastRunError": { "nullable": true, "type": "string" }, "lastObjectKey": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "blobProviderName": { "type": "string" }, "running": { "type": "boolean", "description": "Whether a run is queued or in progress right now." }, "nextRetryAt": { "nullable": true, "description": "When a failing export is next retried; retries back off from 5 minutes to an hour. Null unless the last run failed.", "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "blobProviderId", "name", "enabled", "format", "schedule", "pathPrefix", "exportedThrough", "lastRunAt", "lastRunStatus", "lastRunError", "lastObjectKey", "createdAt", "updatedAt", "blobProviderName", "running", "nextRetryAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "costExport:update", "llmCost:read" ] } } }, "/v1/deepseek/chat/completions": { "post": { "operationId": "deepseekChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with DeepSeek (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSeekChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSeekChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/deepseek/{agentId}/chat/completions": { "post": { "operationId": "deepseekChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with DeepSeek for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSeekChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepSeekChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/default-user-limits": { "get": { "operationId": "listDefaultUserLimits", "tags": [ "Limits" ], "description": "List the organization's default user limits: the organization-wide default and per-environment overrides.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmLimit:read`](/docs/reference/permissions#llmLimit:read): View token usage limits", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "environmentId", "limitValue", "cleanupInterval", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmLimit:read" ] } }, "post": { "operationId": "createDefaultUserLimit", "tags": [ "Limits" ], "description": "Create a default user limit. Omit environmentId for the org-wide default, or set it for a per-environment override.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmLimit:create`](/docs/reference/permissions#llmLimit:create): Create new usage limits", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] } }, "required": [ "limitValue" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "environmentId", "limitValue", "cleanupInterval", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmLimit:create" ] } } }, "/api/default-user-limits/users": { "get": { "operationId": "listUserLimitUsage", "tags": [ "Limits" ], "description": "List organization members with their spend this window against the limit that applies to them (custom, environment override, or organization default), closest to their limit first.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmLimit:read`](/docs/reference/permissions#llmLimit:read): View token usage limits", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false, "description": "Match users by name or email." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "environmentId", "required": false, "description": "Only users who spent in this environment, with the limit that applies to their requests there." }, { "schema": { "type": "string", "enum": [ "at", "near", "custom", "none" ] }, "in": "query", "name": "status", "required": false, "description": "Only users at or near their limit, on a custom limit, or with no limit." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "nullable": true, "type": "string" }, "source": { "type": "string", "enum": [ "custom", "environment_default", "organization_default", "none" ] }, "environmentId": { "nullable": true, "type": "string" }, "environmentName": { "nullable": true, "type": "string" }, "limitValue": { "nullable": true, "type": "number" }, "cleanupInterval": { "nullable": true, "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "models": { "nullable": true, "type": "array", "items": { "type": "string" } }, "spent": { "type": "number" }, "estimatedUsage": { "type": "boolean" }, "percent": { "nullable": true, "type": "number" }, "status": { "type": "string", "enum": [ "ok", "near", "at" ] }, "customLimitId": { "nullable": true, "type": "string" }, "customReason": { "nullable": true, "type": "string" }, "resetsAt": { "nullable": true, "type": "string" }, "projectedSpend": { "nullable": true, "type": "number" }, "fallbackSpent": { "nullable": true, "type": "number" }, "lastResetAt": { "nullable": true, "type": "string" }, "lastResetByName": { "nullable": true, "type": "string" } }, "required": [ "userId", "name", "email", "image", "source", "environmentId", "environmentName", "limitValue", "cleanupInterval", "models", "spent", "estimatedUsage", "percent", "status", "customLimitId", "customReason", "resetsAt", "projectedSpend", "fallbackSpent", "lastResetAt", "lastResetByName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "at": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "near": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "custom": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "none": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "organizationDefault": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "environmentDefault": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "flaggedCustom": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spent": { "type": "number" }, "spenders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resetsAt": { "nullable": true, "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string" }, "users": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "at": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "near": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "environmentId", "users", "at", "near" ], "additionalProperties": false } } }, "required": [ "total", "at", "near", "custom", "none", "organizationDefault", "environmentDefault", "flaggedCustom", "spent", "spenders", "resetsAt", "environments" ], "additionalProperties": false } }, "required": [ "data", "pagination", "summary" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmLimit:read" ] } } }, "/api/default-user-limits/users/{userId}/reset": { "post": { "operationId": "resetUserLimitUsage", "tags": [ "Limits" ], "description": "Start a user's limit usage over from $0 now so their requests are allowed again. The next scheduled reset is unchanged and past usage stays in cost reports.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmLimit:update`](/docs/reference/permissions#llmLimit:update): Modify existing usage limits", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "resetAt": { "type": "string" } }, "required": [ "userId", "resetAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmLimit:update" ] } } }, "/api/default-user-limits/{id}": { "patch": { "operationId": "updateDefaultUserLimit", "tags": [ "Limits" ], "description": "Update a default user limit (organization-wide or per-environment).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmLimit:update`](/docs/reference/permissions#llmLimit:update): Modify existing usage limits", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "environmentId", "limitValue", "cleanupInterval", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmLimit:update" ] } }, "delete": { "operationId": "deleteDefaultUserLimit", "tags": [ "Limits" ], "description": "Delete a default user limit (organization-wide or per-environment).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmLimit:delete`](/docs/reference/permissions#llmLimit:delete): Remove usage limits", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmLimit:delete" ] } } }, "/api/desktop-devices": { "get": { "operationId": "getDesktopDevices", "tags": [ "Desktop Devices" ], "description": "The signed-in user's devices, with the state of each desktop MCP catalog item on them.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "online": { "type": "boolean" }, "lastPolledAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "programVersion": { "nullable": true, "type": "string" }, "programUpdate": { "nullable": true, "type": "object", "properties": { "version": { "nullable": true, "type": "string" } }, "required": [ "version" ], "additionalProperties": false }, "programAutoUpdate": { "type": "boolean" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "name": { "type": "string" }, "state": { "nullable": true, "type": "string", "enum": [ "no_command", "starting", "running", "failed", "stopped" ] }, "lastError": { "nullable": true, "type": "string" }, "command": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "toolCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "catalogId", "name", "state", "lastError", "command", "url", "enabled", "toolCount" ], "additionalProperties": false } } }, "required": [ "id", "name", "platform", "online", "lastPolledAt", "createdAt", "programVersion", "programUpdate", "programAutoUpdate", "servers" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/{id}": { "delete": { "operationId": "deleteDesktopDevice", "tags": [ "Desktop Devices" ], "description": "Remove the signed-in user's device. Its device key stops working.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/{id}/servers/{catalogId}": { "put": { "operationId": "updateDesktopDeviceServer", "tags": [ "Desktop Devices" ], "description": "Start or stop one MCP server on the signed-in user's device. A stopped MCP server stays stopped.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "online": { "type": "boolean" }, "lastPolledAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "programVersion": { "nullable": true, "type": "string" }, "programUpdate": { "nullable": true, "type": "object", "properties": { "version": { "nullable": true, "type": "string" } }, "required": [ "version" ], "additionalProperties": false }, "programAutoUpdate": { "type": "boolean" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "name": { "type": "string" }, "state": { "nullable": true, "type": "string", "enum": [ "no_command", "starting", "running", "failed", "stopped" ] }, "lastError": { "nullable": true, "type": "string" }, "command": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "toolCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "catalogId", "name", "state", "lastError", "command", "url", "enabled", "toolCount" ], "additionalProperties": false } } }, "required": [ "id", "name", "platform", "online", "lastPolledAt", "createdAt", "programVersion", "programUpdate", "programAutoUpdate", "servers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/{id}/servers/{catalogId}/restart": { "post": { "operationId": "restartDesktopDeviceServer", "tags": [ "Desktop Devices" ], "description": "Make the tunnel client stop one MCP server on the signed-in user's device and start it again.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/{id}/servers/{catalogId}/test": { "post": { "operationId": "testDesktopDeviceServer", "tags": [ "Desktop Devices" ], "description": "Ask one MCP server on the signed-in user's device for its tool list, through the tunnel. Nothing is stored.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "toolCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "durationMs": { "type": "number" } }, "required": [ "toolCount", "durationMs" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/{id}/servers/{catalogId}/log": { "get": { "operationId": "getDesktopDeviceServerLog", "tags": [ "Desktop Devices" ], "description": "The last lines one MCP server on the signed-in user's device wrote to stderr.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } } }, "required": [ "lines" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/sign-in": { "post": { "operationId": "startDesktopDeviceSignIn", "tags": [ "Desktop Devices" ], "description": "Called by the tunnel client: start a sign-in that its user approves in the browser.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceName": { "type": "string", "minLength": 1, "maxLength": 64 }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "setupCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" } }, "required": [ "deviceName", "platform" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deviceCode": { "type": "string" }, "userCode": { "type": "string" }, "verificationPath": { "type": "string" }, "expiresAt": { "type": "string" }, "interval": { "type": "number" }, "approveInArchestra": { "type": "boolean" } }, "required": [ "id", "deviceCode", "userCode", "verificationPath", "expiresAt", "interval", "approveInArchestra" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/setup-codes": { "post": { "operationId": "createDesktopDeviceSetupCode", "tags": [ "Desktop Devices" ], "description": "A setup code for the MCP bridge setup dialog of the signed-in user. Its command carries the code, and the dialog then shows the sign-in that the command starts.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "setupCode": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "setupCode", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/setup-codes/{setupCode}/sign-in": { "get": { "operationId": "getDesktopDeviceSetupSignIn", "tags": [ "Desktop Devices" ], "description": "The sign-in that the command of this setup code started, for the signed-in user who got the code. Null while there is none.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "in": "path", "name": "setupCode", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "deviceName": { "type": "string" }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "userCode": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "id", "deviceName", "platform", "userCode", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/sign-in/poll": { "post": { "operationId": "pollDesktopDeviceSignIn", "tags": [ "Desktop Devices" ], "description": "Called by the tunnel client: poll for the user's answer to its sign-in.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ] }, "tunnelId": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/sign-in/{id}": { "get": { "operationId": "getDesktopDeviceSignIn", "tags": [ "Desktop Devices" ], "description": "A pending device sign-in, for the approval page.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceName": { "type": "string" }, "platform": { "type": "string", "enum": [ "macos", "linux", "windows" ] }, "userCode": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "deviceName", "platform", "userCode", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/desktop-devices/sign-in/{id}/decision": { "post": { "operationId": "decideDesktopDeviceSignIn", "tags": [ "Desktop Devices" ], "description": "Approve or deny a device sign-in. Approval registers the device for the signed-in user and replaces their earlier device.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] } }, "required": [ "decision" ] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-f0-9]{48}$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approved", "denied" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/tunnels/{tunnelId}": { "get": { "operationId": "getDesktopTunnel", "tags": [ "Desktop Tunnel" ], "description": "Tunnel metadata for the tunnel client, with the desktop MCP catalog items its user installed, the command or URL of each, and the arguments the user added to the command.", "parameters": [ { "schema": { "type": "string", "pattern": "^tunnel_[a-z0-9]{32}$" }, "in": "path", "name": "tunnelId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "catalog_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "command": { "nullable": true, "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "url": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "name", "command", "arguments", "url", "enabled" ], "additionalProperties": false } }, "program": { "nullable": true, "type": "object", "properties": { "version": { "nullable": true, "type": "string" }, "sha256": { "type": "string" }, "auto_update": { "type": "boolean" } }, "required": [ "version", "sha256", "auto_update" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "catalog_items", "program" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteDesktopTunnel", "tags": [ "Desktop Tunnel" ], "description": "Called by the tunnel client when its user uninstalls it: remove the device. Its device key stops working.", "parameters": [ { "schema": { "type": "string", "pattern": "^tunnel_[a-z0-9]{32}$" }, "in": "path", "name": "tunnelId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tunnels/{tunnelId}/poll": { "get": { "operationId": "pollDesktopTunnel", "tags": [ "Desktop Tunnel" ], "description": "Long poll for the MCP messages that wait for the device. Answers 204 when none came before the wait ended.", "parameters": [ { "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 30000, "type": "integer", "minimum": 0, "maximum": 600000 }, "in": "query", "name": "timeout_ms", "required": false }, { "schema": { "type": "string", "pattern": "^tunnel_[a-z0-9]{32}$" }, "in": "path", "name": "tunnelId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "commands": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string" }, "command_type": { "type": "string", "enum": [ "jsonrpc" ] }, "channel": { "type": "string" }, "created_at": { "type": "string" }, "response_timeout": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "jsonrpc": { "type": "object", "additionalProperties": {} } }, "required": [ "request_id", "command_type", "channel", "created_at", "response_timeout", "headers", "jsonrpc" ], "additionalProperties": false } } }, "required": [ "commands" ], "additionalProperties": false } } } }, "204": { "description": "Default Response" }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/tunnels/{tunnelId}/response": { "post": { "operationId": "respondDesktopTunnel", "tags": [ "Desktop Tunnel" ], "description": "The tunnel client's answer for one polled MCP message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "channel": { "type": "string" }, "resp_json": { "nullable": true, "type": "object", "additionalProperties": {} }, "resp_headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "resp_code": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resp_type": { "default": "jsonrpc_response", "type": "string", "enum": [ "jsonrpc_response", "jsonrpc_notify", "notify_ack", "session_termination_response" ] }, "resp_timing": {} }, "required": [ "request_id", "resp_code" ] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^tunnel_[a-z0-9]{32}$" }, "in": "path", "name": "tunnelId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/dev-feedback/setup": { "get": { "operationId": "getDevFeedbackSetup", "tags": [ "Dev Feedback" ], "description": "Whether a Slack bot and channel are picked for feedback\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "channelName": { "nullable": true, "type": "string" } }, "required": [ "configured", "channelName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "saveDevFeedbackSetup", "tags": [ "Dev Feedback" ], "description": "Pick the Slack bot and channel feedback posts to (joins a public channel)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "botId": { "type": "string", "minLength": 1, "maxLength": 64 }, "channelId": { "type": "string", "pattern": "^[CG][A-Z0-9]+$" } }, "required": [ "botId", "channelId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "channelName": { "nullable": true, "type": "string" } }, "required": [ "configured", "channelName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/dev-feedback/setup/bots": { "get": { "operationId": "listDevFeedbackBots", "tags": [ "Dev Feedback" ], "description": "List the chatops Slack bots feedback can post as\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/dev-feedback/setup/bots/{botId}/channels": { "get": { "operationId": "listDevFeedbackChannels", "tags": [ "Dev Feedback" ], "description": "List the Slack channels a bot can post feedback to\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "botId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isPrivate": { "type": "boolean" } }, "required": [ "id", "name", "isPrivate" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/dev-feedback/comments": { "get": { "operationId": "getDevFeedbackComments", "tags": [ "Dev Feedback" ], "description": "List open UI feedback comments pinned on a route\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "route", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string", "minLength": 1, "maxLength": 512 }, "selector": { "type": "string", "maxLength": 2048 }, "label": { "type": "string", "maxLength": 512 }, "elementX": { "type": "number", "minimum": 0, "maximum": 1 }, "elementY": { "type": "number", "minimum": 0, "maximum": 1 }, "viewportX": { "type": "number", "minimum": 0, "maximum": 1 }, "viewportY": { "type": "number", "minimum": 0, "maximum": 1 }, "id": { "type": "string" }, "text": { "type": "string" }, "authorName": { "type": "string" }, "replyCount": { "type": "number" }, "permalink": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "route", "selector", "label", "elementX", "elementY", "viewportX", "viewportY", "id", "text", "authorName", "replyCount", "permalink", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createDevFeedbackComment", "tags": [ "Dev Feedback" ], "description": "Post a UI feedback comment, with a screenshot and optional clip, to the feedback Slack channel\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "type": "string", "minLength": 1, "maxLength": 512 }, "selector": { "type": "string", "maxLength": 2048 }, "label": { "type": "string", "maxLength": 512 }, "elementX": { "type": "number", "minimum": 0, "maximum": 1 }, "elementY": { "type": "number", "minimum": 0, "maximum": 1 }, "viewportX": { "type": "number", "minimum": 0, "maximum": 1 }, "viewportY": { "type": "number", "minimum": 0, "maximum": 1 }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "url": { "type": "string", "maxLength": 2048 }, "viewport": { "type": "string", "maxLength": 32 }, "screenshot": { "type": "object", "properties": { "mimeType": { "type": "string", "enum": [ "image/png", "image/jpeg" ] }, "base64": { "type": "string", "minLength": 1 } }, "required": [ "mimeType", "base64" ] }, "clip": { "type": "object", "properties": { "mimeType": { "type": "string", "enum": [ "video/mp4", "video/webm" ] }, "base64": { "type": "string", "minLength": 1 } }, "required": [ "mimeType", "base64" ] } }, "required": [ "route", "selector", "label", "elementX", "elementY", "viewportX", "viewportY", "text", "url", "viewport" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "type": "string", "minLength": 1, "maxLength": 512 }, "selector": { "type": "string", "maxLength": 2048 }, "label": { "type": "string", "maxLength": 512 }, "elementX": { "type": "number", "minimum": 0, "maximum": 1 }, "elementY": { "type": "number", "minimum": 0, "maximum": 1 }, "viewportX": { "type": "number", "minimum": 0, "maximum": 1 }, "viewportY": { "type": "number", "minimum": 0, "maximum": 1 }, "id": { "type": "string" }, "text": { "type": "string" }, "authorName": { "type": "string" }, "replyCount": { "type": "number" }, "permalink": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "route", "selector", "label", "elementX", "elementY", "viewportX", "viewportY", "id", "text", "authorName", "replyCount", "permalink", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/dev-feedback/comments/{commentId}/replies": { "get": { "operationId": "getDevFeedbackReplies", "tags": [ "Dev Feedback" ], "description": "List the Slack thread replies of a UI feedback comment\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "in": "path", "name": "commentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "authorName": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "authorName", "text", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createDevFeedbackReply", "tags": [ "Dev Feedback" ], "description": "Reply in the Slack thread of a UI feedback comment\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "text" ] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "in": "path", "name": "commentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "authorName": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "authorName", "text", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/dev-feedback/comments/{commentId}/resolve": { "post": { "operationId": "resolveDevFeedbackComment", "tags": [ "Dev Feedback" ], "description": "Resolve a UI feedback comment (marks its Slack message resolved)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+\\.\\d+$" }, "in": "path", "name": "commentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/environments/labels/keys": { "get": { "operationId": "environmentLabelKeys", "tags": [ "Organization" ], "description": "Get all label keys used by environments\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:read`](/docs/reference/permissions#environment:read): View and list deployment environments", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:read" ] } } }, "/api/environments/labels/values": { "get": { "operationId": "environmentLabelValues", "tags": [ "Organization" ], "description": "Get all label values used by environments\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:read`](/docs/reference/permissions#environment:read): View and list deployment environments", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:read" ] } } }, "/api/environments": { "get": { "operationId": "listEnvironments", "tags": [ "Organization" ], "description": "List org-level deployment environments with their assigned catalog counts, plus the count of catalog items with no environment (the default environment).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:read`](/docs/reference/permissions#environment:read): View and list deployment environments", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "namespace": { "nullable": true, "type": "string" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "validationRegex": { "nullable": true, "type": "string" }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "sortOrder": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "assignedCatalogCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "canDeploy": { "type": "boolean" }, "deployKinds": { "type": "array", "items": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "knowledgeSource" ] } } }, "required": [ "id", "organizationId", "name", "description", "namespace", "networkPolicy", "validationRegex", "trustedImageRegistries", "sortOrder", "createdAt", "updatedAt", "assignedCatalogCount", "labels", "canDeploy", "deployKinds" ], "additionalProperties": false } }, "defaultAssignedCatalogCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "resourceDefaults": { "type": "object", "properties": { "mcpRegistry": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "app": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agent": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpGateway": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "knowledgeSource": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "mcpRegistry", "app", "agent", "mcpGateway", "knowledgeSource" ], "additionalProperties": false } }, "required": [ "environments", "defaultAssignedCatalogCount", "resourceDefaults" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:read" ] } }, "post": { "operationId": "createEnvironment", "tags": [ "Organization" ], "description": "Create an org-level deployment environment.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:create`](/docs/reference/permissions#environment:create): Create deployment environments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "nullable": true, "type": "string", "maxLength": 500 }, "namespace": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$" } }, "allowedCidrs": { "maxItems": 500, "type": "array", "items": { "type": "string" } } } }, "restricted": { "not": {} }, "validationRegex": { "nullable": true, "type": "string", "maxLength": 1000 }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "namespace": { "nullable": true, "type": "string" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "validationRegex": { "nullable": true, "type": "string" }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "sortOrder": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "description", "namespace", "networkPolicy", "validationRegex", "trustedImageRegistries", "sortOrder", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:create" ] } } }, "/api/environments/{id}": { "get": { "operationId": "getEnvironment", "tags": [ "Organization" ], "description": "Read an org-level deployment environment by ID.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:read`](/docs/reference/permissions#environment:read): View and list deployment environments", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "namespace": { "nullable": true, "type": "string" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "validationRegex": { "nullable": true, "type": "string" }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "sortOrder": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "description", "namespace", "networkPolicy", "validationRegex", "trustedImageRegistries", "sortOrder", "createdAt", "updatedAt", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:read" ] } }, "patch": { "operationId": "updateEnvironment", "tags": [ "Organization" ], "description": "Update an environment's name, description, namespace, network policy, and restricted flag. When the namespace or network policy changes and the runtime is enabled, all MCP servers assigned to this environment are reconciled.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:update`](/docs/reference/permissions#environment:update): Modify deployment environments, including the org default environment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "nullable": true, "type": "string", "maxLength": 500 }, "namespace": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$" } }, "allowedCidrs": { "maxItems": 500, "type": "array", "items": { "type": "string" } } } }, "restricted": { "not": {} }, "validationRegex": { "nullable": true, "type": "string", "maxLength": 1000 }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "namespace": { "nullable": true, "type": "string" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "validationRegex": { "nullable": true, "type": "string" }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "sortOrder": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "description", "namespace", "networkPolicy", "validationRegex", "trustedImageRegistries", "sortOrder", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:update" ] } }, "delete": { "operationId": "deleteEnvironment", "tags": [ "Organization" ], "description": "Delete an org-level environment. Fails with 409 if any catalog items are still assigned to it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:delete`](/docs/reference/permissions#environment:delete): Delete deployment environments", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:delete" ] } } }, "/api/environments/defaults": { "patch": { "operationId": "updateEnvironmentResourceDefaults", "tags": [ "Organization" ], "description": "Configure which environment newly created resources of each kind land in when their creator does not pick one. Omitted kinds are left unchanged; an explicit null resets that kind to the default environment.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:update`](/docs/reference/permissions#environment:update): Modify deployment environments, including the org default environment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcpRegistry": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "app": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agent": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpGateway": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "knowledgeSource": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcpRegistry": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "app": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agent": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpGateway": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "knowledgeSource": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "mcpRegistry", "app", "agent", "mcpGateway", "knowledgeSource" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:update" ] } } }, "/api/environments/bulk": { "delete": { "operationId": "bulkDeleteEnvironments", "tags": [ "Organization" ], "description": "Delete several org-level environments in one request. An environment that still has catalog items assigned to it cannot be deleted; it is reported in `failed` with that reason while the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:delete`](/docs/reference/permissions#environment:delete): Delete deployment environments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:delete" ] } } }, "/api/skills/external": { "get": { "operationId": "getExternalMcpSkills", "tags": [ "Skills" ], "description": "List Skills dynamically projected from the caller's accessible MCP server installations.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "environmentId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "serverName": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "uri": { "type": "string" }, "resources": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "digest": { "type": "string" } }, "required": [ "uri", "digest" ], "additionalProperties": false } }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usageUserCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "source", "id", "catalogId", "mcpServerId", "scope", "serverName", "icon", "name", "description", "uri", "resources", "usageCount", "usageUserCount", "lastUsedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read", "skill:read" ] } } }, "/api/skills/external/usage-statistics": { "get": { "operationId": "getExternalMcpSkillUsageStatistics", "tags": [ "Skills" ], "description": "Get recent activation statistics for one external MCP Skill from an accessible installation.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "mcpServerId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "uri", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "user", "service_account", "unattributed" ] }, "total": { "type": "number" } }, "required": [ "userId", "name", "kind", "total" ], "additionalProperties": false } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "userId": { "nullable": true, "type": "string" }, "count": { "type": "number" } }, "required": [ "date", "userId", "count" ], "additionalProperties": false } } }, "required": [ "since", "users", "daily" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read", "skill:read" ] } } }, "/api/skills/external/{id}": { "get": { "operationId": "getExternalMcpSkill", "tags": [ "Skills" ], "description": "Fetch and digest-verify the current bytes of an external MCP Skill from one accessible installation.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "mcpServerId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "external_mcp" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpServerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "serverName": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "uri": { "type": "string" }, "resources": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "digest": { "type": "string" } }, "required": [ "uri", "digest" ], "additionalProperties": false } }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usageUserCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "content": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "kind": { "type": "string", "enum": [ "script", "reference", "asset" ] } }, "required": [ "path", "content", "encoding", "kind" ], "additionalProperties": false } } }, "required": [ "source", "id", "catalogId", "mcpServerId", "scope", "serverName", "icon", "name", "description", "uri", "resources", "usageCount", "usageUserCount", "lastUsedAt", "content", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read", "skill:read" ] } } }, "/v1/gemini/embeddings": { "post": { "operationId": "geminiEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Gemini (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/gemini/{agentId}/embeddings": { "post": { "operationId": "geminiEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Gemini for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/gemini/v1beta/models/{model}:generateContent": { "post": { "summary": "Generate content using Gemini", "tags": [ "LLM Proxy" ], "description": "Generate content using Gemini (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "model", "required": true, "description": "The model to use" }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-shared-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "OAuth access token as a Bearer credential." }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "x-archestra-virtual-key", "required": false, "description": "Passthrough virtual key used for proxy authentication." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-api-key", "required": false, "description": "API key for Google Gemini. Required for Google AI Studio mode, optional for Vertex AI mode (uses ADC)." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-user-project", "required": false, "description": "Google Cloud quota project for OAuth-authenticated requests." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/gemini/v1beta/models/{model}:streamGenerateContent": { "post": { "summary": "Stream generated content using Gemini", "tags": [ "LLM Proxy" ], "description": "Stream generated content using Gemini (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "model", "required": true, "description": "The model to use" }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-shared-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "OAuth access token as a Bearer credential." }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "x-archestra-virtual-key", "required": false, "description": "Passthrough virtual key used for proxy authentication." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-api-key", "required": false, "description": "API key for Google Gemini. Required for Google AI Studio mode, optional for Vertex AI mode (uses ADC)." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-user-project", "required": false, "description": "Google Cloud quota project for OAuth-authenticated requests." } ], "responses": { "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/gemini/{agentId}/v1beta/models/{model}:generateContent": { "post": { "summary": "Generate content using Gemini (specific agent)", "tags": [ "LLM Proxy" ], "description": "Generate content using Gemini with specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "model", "required": true, "description": "The model to use" }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-shared-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "OAuth access token as a Bearer credential." }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "x-archestra-virtual-key", "required": false, "description": "Passthrough virtual key used for proxy authentication." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-api-key", "required": false, "description": "API key for Google Gemini. Required for Google AI Studio mode, optional for Vertex AI mode (uses ADC)." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-user-project", "required": false, "description": "Google Cloud quota project for OAuth-authenticated requests." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/gemini/{agentId}/v1beta/models/{model}:streamGenerateContent": { "post": { "summary": "Stream generated content using Gemini (specific agent)", "tags": [ "LLM Proxy" ], "description": "Stream generated content using Gemini with specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "model", "required": true, "description": "The model to use" }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-vertex-ai-llm-shared-request-type", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "OAuth access token as a Bearer credential." }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "x-archestra-virtual-key", "required": false, "description": "Passthrough virtual key used for proxy authentication." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-api-key", "required": false, "description": "API key for Google Gemini. Required for Google AI Studio mode, optional for Vertex AI mode (uses ADC)." }, { "schema": { "type": "string" }, "in": "header", "name": "x-goog-user-project", "required": false, "description": "Google Cloud quota project for OAuth-authenticated requests." } ], "responses": { "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/git-credentials": { "get": { "operationId": "listGitCredentials", "tags": [ "Git Credentials" ], "description": "List the organization's GitHub Apps and GitLab access tokens. Token values are never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "kind": { "type": "string", "enum": [ "github_app", "gitlab_token" ] }, "webUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "provider", "kind", "webUrl", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } } }, "/api/git-credentials/gitlab": { "post": { "operationId": "createGitlabToken", "tags": [ "Git Credentials" ], "description": "Save a GitLab access token after GitLab confirms it can read the API. The token is stored as a secret and never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:create`](/docs/reference/permissions#credential:create): Create saved credentials", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "gitlabUrl": { "default": "https://gitlab.com", "description": "GitLab web address, e.g. https://gitlab.com", "type": "string" }, "token": { "type": "string", "minLength": 1, "description": "A project, group, or personal access token. Write-only: never returned." } }, "required": [ "name", "token" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "kind": { "type": "string", "enum": [ "github_app", "gitlab_token" ] }, "webUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "provider", "kind", "webUrl", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:create" ] } } }, "/api/git-credentials/{id}/repositories": { "get": { "operationId": "listGitCredentialRepositories", "tags": [ "Git Credentials" ], "description": "Repositories a Git credential can reach: the GitHub App's installed repositories, or the GitLab projects the token is a member of.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "private": { "type": "boolean" }, "defaultBranch": { "nullable": true, "type": "string" } }, "required": [ "path", "private", "defaultBranch" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } } }, "/api/git-credentials/{id}/namespaces": { "get": { "operationId": "listGitCredentialNamespaces", "tags": [ "Git Credentials" ], "description": "Where a Git credential can create repositories: the GitHub App's account, or the GitLab groups the token can create projects in. An empty string is the GitLab token owner's own namespace.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } } }, "/api/github-actions/token": { "post": { "operationId": "exchangeGitHubActionsToken", "tags": [ "GitHub Actions" ], "description": "Trade a GitHub Actions OIDC token from a pull_request workflow run for an MCP gateway token, plus a GitHub App installation token for that repository. The gateway token acts as the pull request's author, for runs the author started, or, when the gateway's GitHub Actions setting has actAs \"actor\", as whoever started the run. The gateway must allow the repository and workflow, and that person must have connected GitHub through the gateway's GitHub App.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 16384 }, "resource": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "token", "resource" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "github_token": { "type": "string" }, "github_token_expires_at": { "type": "string" }, "github_login": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "github_token", "github_token_expires_at", "github_login", "user_id" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_token", "not_trusted", "not_author", "not_linked", "ambiguous_link", "forbidden", "rate_limited", "github_error", "server_error" ] }, "message": { "type": "string" }, "login": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_token", "not_trusted", "not_author", "not_linked", "ambiguous_link", "forbidden", "rate_limited", "github_error", "server_error" ] }, "message": { "type": "string" }, "login": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_token", "not_trusted", "not_author", "not_linked", "ambiguous_link", "forbidden", "rate_limited", "github_error", "server_error" ] }, "message": { "type": "string" }, "login": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_token", "not_trusted", "not_author", "not_linked", "ambiguous_link", "forbidden", "rate_limited", "github_error", "server_error" ] }, "message": { "type": "string" }, "login": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_token", "not_trusted", "not_author", "not_linked", "ambiguous_link", "forbidden", "rate_limited", "github_error", "server_error" ] }, "message": { "type": "string" }, "login": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_token", "not_trusted", "not_author", "not_linked", "ambiguous_link", "forbidden", "rate_limited", "github_error", "server_error" ] }, "message": { "type": "string" }, "login": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/github-app-configs": { "get": { "operationId": "listGithubAppConfigs", "tags": [ "GitHub App Configs" ], "description": "List organization GitHub App configurations. The private key is never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "githubUrl": { "type": "string" }, "appId": { "type": "string" }, "installationId": { "type": "string" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt", "githubUrl", "appId", "installationId" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } }, "post": { "operationId": "createGithubAppConfig", "tags": [ "GitHub App Configs" ], "description": "Create a GitHub App configuration. The private key is stored as a secret and never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:create`](/docs/reference/permissions#credential:create): Create saved credentials", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "githubUrl": { "type": "string", "format": "uri" }, "appId": { "type": "string", "minLength": 1 }, "installationId": { "type": "string", "minLength": 1 }, "privateKey": { "type": "string", "minLength": 1, "description": "GitHub App private key PEM" } }, "required": [ "name", "appId", "installationId", "privateKey" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "githubUrl": { "type": "string" }, "appId": { "type": "string" }, "installationId": { "type": "string" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt", "githubUrl", "appId", "installationId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:create" ] } } }, "/api/github-app-configs/{id}": { "get": { "operationId": "getGithubAppConfig", "tags": [ "GitHub App Configs" ], "description": "Get a GitHub App configuration. The private key is never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "githubUrl": { "type": "string" }, "appId": { "type": "string" }, "installationId": { "type": "string" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt", "githubUrl", "appId", "installationId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateGithubAppConfig", "tags": [ "GitHub App Configs" ], "description": "Update a GitHub App configuration. Provide a private key only to rotate it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "githubUrl": { "type": "string", "format": "uri" }, "appId": { "type": "string", "minLength": 1 }, "installationId": { "type": "string", "minLength": 1 }, "privateKey": { "type": "string", "minLength": 1, "description": "GitHub App private key PEM" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "githubUrl": { "type": "string" }, "appId": { "type": "string" }, "installationId": { "type": "string" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt", "githubUrl", "appId", "installationId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteGithubAppConfig", "tags": [ "GitHub App Configs" ], "description": "Delete a GitHub App configuration and its stored private key.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/github-copilot-app/manifest": { "post": { "operationId": "startCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "Start registering a GitHub App, from a manifest, that makes Copilot requests for a GitHub organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "organization" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "manifest": { "type": "string" } }, "required": [ "url", "manifest" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/manifest/complete": { "post": { "operationId": "completeCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "Exchange GitHub's one-time code for the new App; it is stored once installed\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 512 }, "state": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "code", "state" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "account": { "type": "string" }, "appId": { "type": "string" }, "accountUrl": { "type": "string" }, "htmlUrl": { "type": "string" }, "installUrl": { "type": "string" }, "settingsUrl": { "type": "string" } }, "required": [ "name", "slug", "account", "appId", "accountUrl", "htmlUrl", "installUrl", "settingsUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/github-copilot-app/pending": { "get": { "operationId": "getPendingCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "The Copilot GitHub App created during setup that is not installed yet\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "account": { "type": "string" }, "appId": { "type": "string" }, "accountUrl": { "type": "string" }, "htmlUrl": { "type": "string" }, "installUrl": { "type": "string" }, "settingsUrl": { "type": "string" } }, "required": [ "name", "slug", "account", "appId", "accountUrl", "htmlUrl", "installUrl", "settingsUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } }, "delete": { "operationId": "discardCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "Forget the Copilot GitHub App created during setup so setup can start over\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/install": { "post": { "operationId": "installCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "Store the new App as a shared GitHub Copilot key once it is installed on the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "replaceKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "installed" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organization": { "type": "string" }, "modelIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "id", "organization", "modelIds" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/credential": { "post": { "operationId": "connectCopilotGithubAppCredential", "tags": [ "LLM Provider API Keys" ], "description": "Use a GitHub App the organization already connected. Says so when its installation lacks Copilot Requests\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organization": { "type": "string", "minLength": 1, "maxLength": 500 }, "replaceKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "credentialId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "installed" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organization": { "type": "string" }, "modelIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "id", "organization", "modelIds" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "needs_permission" ] }, "appName": { "type": "string" }, "organization": { "type": "string" }, "settingsUrl": { "type": "string" } }, "required": [ "status", "appName", "organization", "settingsUrl" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/organization/check": { "post": { "operationId": "checkCopilotGithubOrganization", "tags": [ "LLM Provider API Keys" ], "description": "Check that a name or GitHub address names a GitHub organization, before connecting an existing App\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "string", "maxLength": 500 } }, "required": [ "organization" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "organization", "organizationName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/existing/validate": { "post": { "operationId": "validateExistingCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "Check an existing GitHub App and its installation on the organization; returns the private key's fingerprint\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "pattern": "^\\d+$" }, "organization": { "type": "string", "minLength": 1, "maxLength": 500 }, "privateKey": { "type": "string", "minLength": 1, "maxLength": 20000 }, "replaceKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "appId", "privateKey" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint": { "type": "string" }, "installationId": { "type": "string" }, "organization": { "type": "string" } }, "required": [ "fingerprint", "installationId", "organization" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/existing": { "post": { "operationId": "connectExistingCopilotGithubApp", "tags": [ "LLM Provider API Keys" ], "description": "Store an existing GitHub App as a shared GitHub Copilot key, or replace the App credentials of one\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:create`](/docs/reference/permissions#llmProviderApiKey:create): Add new LLM provider API keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "pattern": "^\\d+$" }, "organization": { "type": "string", "minLength": 1, "maxLength": 500 }, "privateKey": { "type": "string", "minLength": 1, "maxLength": 20000 }, "replaceKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "appId", "privateKey" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "installed" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organization": { "type": "string" }, "modelIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "id", "organization", "modelIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:create" ] } } }, "/api/github-copilot-app/keys/{id}": { "get": { "operationId": "getCopilotGithubAppKeySummary", "tags": [ "LLM Provider API Keys" ], "description": "The organization, App (name, icon, GitHub page) and key fingerprint of an organization's GitHub Copilot subscription\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "nullable": true, "type": "string" }, "appId": { "type": "string" }, "appName": { "nullable": true, "type": "string" }, "appIcon": { "nullable": true, "type": "string" }, "appUrl": { "nullable": true, "type": "string" }, "githubUrl": { "type": "string" }, "fingerprint": { "type": "string" } }, "required": [ "organization", "appId", "appName", "appIcon", "appUrl", "githubUrl", "fingerprint" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/github-copilot-auth/device/start": { "post": { "operationId": "githubCopilotDeviceAuthStart", "tags": [ "GitHub Copilot Auth" ], "description": "Start the GitHub device flow used to connect a GitHub Copilot subscription\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string" }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "interval": { "type": "number" }, "expiresIn": { "type": "number" } }, "required": [ "deviceCode", "userCode", "verificationUri", "interval", "expiresIn" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/github-copilot-auth/device/poll": { "post": { "operationId": "githubCopilotDeviceAuthPoll", "tags": [ "GitHub Copilot Auth" ], "description": "Poll the GitHub device flow once; returns the GitHub OAuth token when the user has authorized\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "slow_down" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete" ] }, "accessToken": { "type": "string" } }, "required": [ "status", "accessToken" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/github-copilot/chat/completions": { "post": { "operationId": "githubCopilotChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with GitHub Copilot (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string" }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "model" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/{agentId}/chat/completions": { "post": { "operationId": "githubCopilotChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with GitHub Copilot for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string" }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "model" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/v1/messages": { "post": { "operationId": "githubCopilotMessagesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a native Anthropic Messages response with GitHub Copilot\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-beta", "required": false, "description": "Beta features to enable (comma-separated)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header (Bearer token for OAuth)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/{agentId}/v1/messages": { "post": { "operationId": "githubCopilotMessagesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a native Anthropic Messages response with GitHub Copilot\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-beta", "required": false, "description": "Beta features to enable (comma-separated)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header (Bearer token for OAuth)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicMessagesResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/v1/messages/count_tokens": { "post": { "operationId": "githubCopilotCountTokensWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Count native Anthropic Messages input tokens with GitHub Copilot\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-beta", "required": false, "description": "Beta features to enable (comma-separated)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header (Bearer token for OAuth)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "input_tokens" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/{agentId}/v1/messages/count_tokens": { "post": { "operationId": "githubCopilotCountTokensWithAgent", "tags": [ "LLM Proxy" ], "description": "Count native Anthropic Messages input tokens with GitHub Copilot\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ] }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ] } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ] } ] } } ] } }, "required": [ "type", "content" ] } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ] } }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-version", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "anthropic-beta", "required": false, "description": "Beta features to enable (comma-separated)" }, { "schema": { "type": "string" }, "in": "header", "name": "x-api-key", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Authorization header (Bearer token for OAuth)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "input_tokens" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/responses": { "post": { "operationId": "githubCopilotResponsesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with GitHub Copilot (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "model", "output" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/{agentId}/responses": { "post": { "operationId": "githubCopilotResponsesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with GitHub Copilot for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "model", "output" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/models": { "get": { "operationId": "githubCopilotListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List GitHub Copilot models (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/github-copilot/{agentId}/models": { "get": { "operationId": "githubCopilotListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List GitHub Copilot models (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/github-pats": { "get": { "operationId": "listGithubPats", "tags": [ "GitHub PATs" ], "description": "List organization GitHub personal access tokens. The token value is never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } }, "post": { "operationId": "createGithubPat", "tags": [ "GitHub PATs" ], "description": "Store a GitHub personal access token. The token is stored as a secret and never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:create`](/docs/reference/permissions#credential:create): Create saved credentials", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1, "description": "GitHub personal access token" } }, "required": [ "name", "token" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:create" ] } } }, "/api/github-pats/{id}": { "put": { "operationId": "updateGithubPat", "tags": [ "GitHub PATs" ], "description": "Rename a stored GitHub token. Provide a token only to rotate it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "token": { "description": "Provide only to rotate the stored token.", "type": "string", "minLength": 1 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteGithubPat", "tags": [ "GitHub PATs" ], "description": "Delete a stored GitHub token and its secret. Rejected while synced skills authenticate with it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/groq/chat/completions": { "post": { "operationId": "groqChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Groq (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroqChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/groq/{agentId}/chat/completions": { "post": { "operationId": "groqChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Groq for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroqChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/guardrails-deployment": { "get": { "operationId": "getGuardrailsDeployment", "tags": [ "Guardrails" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "unsupportedClientAction": { "type": "string", "enum": [ "bypass", "block" ] }, "breakTheGlassEnabled": { "type": "boolean" }, "humanApprovalMode": { "type": "string", "enum": [ "block", "unattended", "everywhere" ] }, "unapprovableBlockMode": { "type": "string", "enum": [ "refuse", "allow" ] }, "environmentOverrides": { "type": "array", "items": { "type": "object", "properties": { "setting": { "type": "string", "enum": [ "humanApprovalMode", "unapprovableBlockMode" ] }, "variable": { "type": "string" } }, "required": [ "setting", "variable" ], "additionalProperties": false } }, "annotatorModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "annotatorLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "featureEnabled": { "type": "boolean" }, "active": { "type": "boolean" } }, "required": [ "enabled", "unsupportedClientAction", "breakTheGlassEnabled", "humanApprovalMode", "unapprovableBlockMode", "environmentOverrides", "annotatorModelId", "annotatorLlmApiKeyId", "featureEnabled", "active" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" }, "put": { "operationId": "updateGuardrailsDeployment", "tags": [ "Guardrails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "unsupportedClientAction": { "type": "string", "enum": [ "bypass", "block" ] }, "breakTheGlassEnabled": { "type": "boolean" }, "humanApprovalMode": { "type": "string", "enum": [ "block", "unattended", "everywhere" ] }, "unapprovableBlockMode": { "type": "string", "enum": [ "refuse", "allow" ] }, "annotatorModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "annotatorLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "unsupportedClientAction": { "type": "string", "enum": [ "bypass", "block" ] }, "breakTheGlassEnabled": { "type": "boolean" }, "humanApprovalMode": { "type": "string", "enum": [ "block", "unattended", "everywhere" ] }, "unapprovableBlockMode": { "type": "string", "enum": [ "refuse", "allow" ] }, "environmentOverrides": { "type": "array", "items": { "type": "object", "properties": { "setting": { "type": "string", "enum": [ "humanApprovalMode", "unapprovableBlockMode" ] }, "variable": { "type": "string" } }, "required": [ "setting", "variable" ], "additionalProperties": false } }, "annotatorModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "annotatorLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "featureEnabled": { "type": "boolean" }, "active": { "type": "boolean" } }, "required": [ "enabled", "unsupportedClientAction", "breakTheGlassEnabled", "humanApprovalMode", "unapprovableBlockMode", "environmentOverrides", "annotatorModelId", "annotatorLlmApiKeyId", "featureEnabled", "active" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/guardrails-policy/annotators/noop": { "post": { "operationId": "annotateGuardrailsTool", "tags": [ "Guardrails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "kind": { "type": "string", "enum": [ "annotation" ] } }, "required": [ "version", "kind" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "answer": { "type": "object", "properties": { "delta": { "type": "object", "properties": {}, "additionalProperties": false }, "requires": { "type": "object", "properties": { "history": { "type": "array", "items": { "not": {} } }, "attention": { "type": "array", "items": { "not": {} } } }, "required": [ "history", "attention" ], "additionalProperties": false }, "emits": { "type": "array", "items": { "not": {} } } }, "required": [ "delta", "requires", "emits" ], "additionalProperties": false } }, "required": [ "version", "answer" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/guardrails-policy": { "get": { "operationId": "getGuardrailsPolicy", "tags": [ "Guardrails" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "content": { "type": "string" }, "contentHash": { "type": "string" }, "updatedBy": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "organizationId", "revision", "content", "contentHash", "updatedBy", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" }, "put": { "operationId": "updateGuardrailsPolicy", "tags": [ "Guardrails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 1048576 }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "content", "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "revision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "content": { "type": "string" }, "contentHash": { "type": "string" }, "updatedBy": { "nullable": true, "type": "string" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "organizationId", "revision", "content", "contentHash", "updatedBy", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/guardrails-policy/validate": { "post": { "operationId": "validateGuardrailsPolicy", "tags": [ "Guardrails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 1048576 } }, "required": [ "content" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "errors", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/health": { "get": { "tags": [ "Health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" } }, "required": [ "name", "status", "version" ], "additionalProperties": false } } } } } } }, "/ready": { "get": { "tags": [ "Health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "maintenance" ] }, "version": { "type": "string" }, "database": { "type": "string", "enum": [ "connected", "not_checked" ] }, "openappa": { "type": "string", "enum": [ "ready", "disabled", "not_checked" ] }, "sandbox": { "type": "string", "enum": [ "ready", "initializing", "disabled", "unreachable" ] }, "sandboxReason": { "type": "string" } }, "required": [ "name", "status", "version", "database", "openappa", "sandbox" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "degraded" ] }, "version": { "type": "string" }, "database": { "type": "string", "enum": [ "connected", "disconnected", "not_checked" ] }, "kubernetes": { "type": "string", "enum": [ "starting" ] }, "openappa": { "type": "string", "enum": [ "starting", "unavailable" ] }, "openappaReason": { "type": "string" } }, "required": [ "name", "status", "version", "database" ], "additionalProperties": false } } } } } } }, "/api/hooks": { "get": { "operationId": "getHooks", "tags": [ "Hooks" ], "description": "List hook files for an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "event": { "type": "string", "enum": [ "session_start", "pre_tool_use", "post_tool_use" ] }, "fileName": { "type": "string" }, "content": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "agentId", "event", "fileName", "content", "requirements", "enabled", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createHook", "tags": [ "Hooks" ], "description": "Create a new hook file for an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "event": { "type": "string", "enum": [ "session_start", "pre_tool_use", "post_tool_use" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*\\.(py|sh)$" }, "content": { "type": "string", "minLength": 1, "maxLength": 65536 }, "requirements": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "enabled": { "type": "boolean" } }, "required": [ "agentId", "event", "fileName", "content" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "event": { "type": "string", "enum": [ "session_start", "pre_tool_use", "post_tool_use" ] }, "fileName": { "type": "string" }, "content": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "agentId", "event", "fileName", "content", "requirements", "enabled", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/hooks/{id}": { "put": { "operationId": "updateHook", "tags": [ "Hooks" ], "description": "Update an existing hook file\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "session_start", "pre_tool_use", "post_tool_use" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*\\.(py|sh)$" }, "content": { "type": "string", "minLength": 1, "maxLength": 65536 }, "requirements": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "event": { "type": "string", "enum": [ "session_start", "pre_tool_use", "post_tool_use" ] }, "fileName": { "type": "string" }, "content": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "agentId", "event", "fileName", "content", "requirements", "enabled", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteHook", "tags": [ "Hooks" ], "description": "Delete a hook file\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/webhooks/incoming-email": { "post": { "tags": [ "Webhooks" ], "description": "Webhook endpoint for incoming email notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "success": { "type": "boolean" }, "processed": { "type": "number" }, "errors": { "type": "number" } }, "required": [ "success" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/agents/{agentId}/email-address": { "get": { "operationId": "getAgentEmailAddress", "tags": [ "Agents" ], "description": "Get the email address for invoking an agent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerEnabled": { "type": "boolean" }, "emailAddress": { "nullable": true, "type": "string" }, "agentIncomingEmailEnabled": { "type": "boolean" }, "agentSecurityMode": { "type": "string", "enum": [ "private", "internal", "public" ] }, "agentAllowedDomain": { "nullable": true, "type": "string" } }, "required": [ "providerEnabled", "emailAddress", "agentIncomingEmailEnabled", "agentSecurityMode", "agentAllowedDomain" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/incoming-email/status": { "get": { "operationId": "getIncomingEmailStatus", "tags": [ "Incoming Email" ], "description": "Get the current incoming email webhook subscription status\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "type": "boolean" }, "subscription": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "subscriptionId": { "type": "string" }, "provider": { "type": "string" }, "webhookUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "subscriptionId", "provider", "webhookUrl", "expiresAt" ], "additionalProperties": false } }, "required": [ "isActive", "subscription" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/incoming-email/setup": { "post": { "operationId": "setupIncomingEmailWebhook", "tags": [ "Incoming Email" ], "description": "Setup or renew incoming email webhook subscription\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookUrl": { "type": "string", "format": "uri" } }, "required": [ "webhookUrl" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriptionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/incoming-email/renew": { "post": { "operationId": "renewIncomingEmailSubscription", "tags": [ "Incoming Email" ], "description": "Renew the incoming email webhook subscription\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriptionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/incoming-email/subscription": { "delete": { "operationId": "deleteIncomingEmailSubscription", "tags": [ "Incoming Email" ], "description": "Delete the incoming email webhook subscription\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/llm-proxy-logs": { "get": { "operationId": "getLlmProxyLogs", "tags": [ "LLM Proxy Logs" ], "description": "List LLM Proxy request logs in the active organization with pagination and sorting. [`log:read`](/docs/reference/permissions#log:read) returns the caller's rows; [`log:admin`](/docs/reference/permissions#log:admin) includes every row in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) returns the caller's rows. [`log:admin`](/docs/reference/permissions#log:admin) includes every row in the active organization.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "profileId", "required": false, "description": "Filter by profile ID (internal Archestra profile)" }, { "schema": { "type": "string" }, "in": "query", "name": "externalAgentId", "required": false, "description": "Filter by external agent ID (from X-Archestra-Agent-Id header)" }, { "schema": { "type": "string" }, "in": "query", "name": "userId", "required": false, "description": "Filter by user ID (from X-Archestra-User-Id header)" }, { "schema": { "type": "string" }, "in": "query", "name": "sessionId", "required": false, "description": "Filter by session ID. A request logged without a session is a session of its own, addressed by its log ID." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by start date (ISO 8601 format)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by end date (ISO 8601 format)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "createdAt", "profileId", "externalAgentId", "model", "userId" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OpenAiChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response.compaction" ] }, "created_at": { "type": "number" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "output", "usage" ], "additionalProperties": {} } ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "gemini:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "bedrock:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cohere:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/GeminiGenerateContentRequest" }, { "type": "object", "properties": { "input_files": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } ] }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/GeminiGenerateContentRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/GeminiGenerateContentResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "gemini:generateContent" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "anthropic:messages", "github-copilot:messages" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ], "additionalProperties": false } }, "required": [ "toolResult" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } }, "required": [ "name", "inputSchema" ], "additionalProperties": false }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ], "additionalProperties": false } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ], "additionalProperties": false }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ], "additionalProperties": false }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ], "additionalProperties": false } }, "required": [ "jsonSchema" ], "additionalProperties": false } }, "required": [ "type", "structure" ], "additionalProperties": false } }, "additionalProperties": false }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ], "additionalProperties": false } }, "required": [ "toolResult" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } }, "required": [ "name", "inputSchema" ], "additionalProperties": false }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ], "additionalProperties": false } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ], "additionalProperties": false }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ], "additionalProperties": false }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ], "additionalProperties": false } }, "required": [ "jsonSchema" ], "additionalProperties": false } }, "required": [ "type", "structure" ], "additionalProperties": false } }, "additionalProperties": false }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "$metadata": { "type": "object", "properties": { "httpStatusCode": { "type": "number" }, "requestId": { "type": "string" }, "attempts": { "type": "number" }, "totalRetryDelay": { "type": "number" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "additionalProperties": false }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered", "malformed_model_output", "malformed_tool_use", "model_context_window_exceeded" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadInputTokens": { "type": "number" }, "cacheWriteInputTokens": { "type": "number" }, "cacheDetails": { "type": "array", "items": { "type": "object", "properties": { "ttl": { "type": "string" }, "inputTokens": { "type": "number" } }, "additionalProperties": false } } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "number" } }, "additionalProperties": false }, "additionalModelResponseFields": { "type": "object", "additionalProperties": {} }, "trace": { "type": "object", "properties": { "guardrail": { "type": "object", "properties": { "inputAssessment": { "type": "object", "additionalProperties": {} }, "outputAssessments": { "type": "object", "additionalProperties": {} }, "modelOutput": { "type": "array", "items": { "type": "string" } }, "actionReason": { "type": "string" } }, "additionalProperties": false }, "promptRouter": { "type": "object", "properties": { "invokedModelId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false } }, "required": [ "output", "stopReason", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "bedrock:converse" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ], "additionalProperties": false } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ], "additionalProperties": false } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "bedrock:invoke" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/CerebrasChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cerebras:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/MistralChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "mistral:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/PerplexityChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/PerplexityChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/PerplexityChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "perplexity:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/GroqChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "groq:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "xai:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/OpenrouterChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/OpenrouterChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OpenrouterChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openrouter:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/VllmChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/VllmChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/VllmChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "vllm:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/OllamaChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/OllamaChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OllamaChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "ollama:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/OllamaNativeChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/OllamaNativeChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OllamaNativeChatResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "ollama-native:chat" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/CohereChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/CohereChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/CohereChatResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cohere:chat" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/ZhipuaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/ZhipuaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/ZhipuaiChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "zhipuai:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/DeepSeekChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/DeepSeekChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/DeepSeekChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "deepseek:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "kimi:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "kimi-code:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string" }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "model" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "github-copilot:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "microsoft-365-copilot:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/MinimaxChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/MinimaxChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/MinimaxChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "minimax:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" }, "target_language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$" } }, "required": [ "model", "messages" ], "additionalProperties": false, "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" }, "target_language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$" } }, "required": [ "model", "messages" ], "additionalProperties": false, "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:realtime" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usage_available": { "type": "boolean" }, "cost_available": { "type": "boolean" }, "usage": { "type": "object", "additionalProperties": {} }, "speech_input": { "type": "string" }, "transcript": { "type": "string" }, "audio": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "audio_omitted": { "type": "string", "enum": [ "too_large" ] }, "upload": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "upload_omitted": { "type": "string", "enum": [ "too_large" ] } }, "required": [ "id", "model", "operation", "content_type", "bytes", "usage_available", "cost_available" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:audio" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usage_available": { "type": "boolean" }, "cost_available": { "type": "boolean" }, "usage": { "type": "object", "additionalProperties": {} }, "speech_input": { "type": "string" }, "transcript": { "type": "string" }, "audio": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "audio_omitted": { "type": "string", "enum": [ "too_large" ] }, "upload": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "upload_omitted": { "type": "string", "enum": [ "too_large" ] } }, "required": [ "id", "model", "operation", "content_type", "bytes", "usage_available", "cost_available" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:audio" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:images", "openai:images" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "perplexity:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "model", "output" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "github-copilot:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/JevDecisionsRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/JevDecisionsRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/JevDecisionsResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "jev:decisions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "turn": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "session": { "type": "object", "additionalProperties": {} }, "input_text": { "type": "string" }, "input_transcript": { "type": "string" } }, "required": [ "model", "turn" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "turn": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "session": { "type": "object", "additionalProperties": {} }, "input_text": { "type": "string" }, "input_transcript": { "type": "string" } }, "required": [ "model", "turn" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "output_transcript": { "type": "string" }, "output_audio": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pcm16" ] }, "sample_rate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "data": { "type": "string" } }, "required": [ "format", "sample_rate", "data" ], "additionalProperties": false }, "output_audio_omitted": { "type": "string", "enum": [ "too_large" ] }, "output": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "usage": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:realtime" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "query": { "type": "string" }, "content_type": { "type": "string" }, "content_length": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "body": {}, "truncated": { "type": "boolean" } }, "required": [ "method", "path" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "query": { "type": "string" }, "content_type": { "type": "string" }, "content_length": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "body": {}, "truncated": { "type": "boolean" } }, "required": [ "method", "path" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "body": {}, "truncated": { "type": "boolean" }, "streamed": { "type": "boolean" } }, "required": [ "status", "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:passthrough", "anthropic:passthrough" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false } ] } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` returns the caller's rows. `log:admin` includes every row in the active organization.", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/summaries": { "get": { "operationId": "getLlmProxyLogSummaries", "tags": [ "LLM Proxy Logs" ], "description": "List LLM Proxy request log metadata without request and response payloads. [`log:read`](/docs/reference/permissions#log:read) returns the caller's rows; [`log:admin`](/docs/reference/permissions#log:admin) includes every row in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) returns the caller's rows. [`log:admin`](/docs/reference/permissions#log:admin) includes every row in the active organization.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "profileId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "externalAgentId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "userId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sessionId", "required": false, "description": "Filter by session ID. A request logged without a session is a session of its own, addressed by its log ID." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "beforeId", "required": false, "description": "Only rows created before this log entry, ordered by creation time then ID at the stored precision. Its total is the entry's zero-based position." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "createdAt", "profileId", "externalAgentId", "model", "userId" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "sessionId": { "nullable": true, "type": "string" }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cost": { "nullable": true, "type": "string" }, "baselineCost": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "failed": { "type": "boolean" }, "type": { "type": "string", "enum": [ "openai:chatCompletions", "openai:responses", "openai:embeddings", "gemini:generateContent", "gemini:embeddings", "anthropic:messages", "bedrock:converse", "bedrock:invoke", "bedrock:embeddings", "cohere:chat", "cohere:embeddings", "cerebras:chatCompletions", "mistral:chatCompletions", "perplexity:chatCompletions", "perplexity:responses", "groq:chatCompletions", "xai:chatCompletions", "xai:responses", "openrouter:chatCompletions", "vllm:chatCompletions", "ollama:chatCompletions", "ollama-native:chat", "zhipuai:chatCompletions", "deepseek:chatCompletions", "minimax:chatCompletions", "kimi:chatCompletions", "kimi-code:chatCompletions", "azure:chatCompletions", "azure:responses", "azure:images", "azure:audio", "openai:audio", "openai:images", "openai:passthrough", "anthropic:passthrough", "openai:realtime", "azure:realtime", "github-copilot:chatCompletions", "github-copilot:responses", "github-copilot:messages", "microsoft-365-copilot:chatCompletions", "archestra:chatCompletions", "voyage:embeddings", "jev:decisions" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "userMessagePreview": { "nullable": true, "type": "string" }, "responseToolNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "responseToolCalls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "responseTextPreview": { "nullable": true, "type": "string" }, "autoRouted": { "type": "boolean" } }, "required": [ "id", "profileId", "externalAgentId", "sessionId", "model", "baselineModel", "billingMode", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cost", "baselineCost", "durationMs", "createdAt", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "type", "externalAgentIdLabel", "requestType", "autoRouted" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` returns the caller's rows. `log:admin` includes every row in the active organization.", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/sessions": { "get": { "operationId": "getLlmProxyLogSessions", "tags": [ "LLM Proxy Logs" ], "description": "List LLM Proxy log sessions with aggregated usage and cost. [`log:read`](/docs/reference/permissions#log:read) returns the caller's sessions; [`log:admin`](/docs/reference/permissions#log:admin) includes every session in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) returns the caller's sessions. [`log:admin`](/docs/reference/permissions#log:admin) includes every session in the active organization.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "profileId", "required": false, "description": "Filter by profile ID (internal Archestra profile)" }, { "schema": { "type": "string" }, "in": "query", "name": "userId", "required": false, "description": "Filter by user ID (from X-Archestra-User-Id header)" }, { "schema": { "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "in": "query", "name": "source", "required": false, "description": "Filter by interaction source" }, { "schema": { "type": "string", "enum": [ "claude", "claude-code", "claude-desktop", "codex", "chatgpt", "copilot-cli", "cursor", "opencode", "kilo", "pi", "kimi-code" ] }, "in": "query", "name": "client", "required": false, "description": "Filter by client app (queries external_agent_id; e.g. claude)" }, { "schema": { "type": "string" }, "in": "query", "name": "sessionId", "required": false, "description": "Filter by session ID. A request logged without a session is a session of its own, addressed by its log ID." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by start date (ISO 8601 format)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by end date (ISO 8601 format)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "attributionLabels": { "description": "Captured attribution labels of lastInteractionId, the request shown in the row. Other requests in the session may have different labels. Null means no snapshot was captured.", "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] } }, "interactionId": { "nullable": true, "type": "string" }, "requestCount": { "type": "number" }, "failedOverCount": { "type": "number", "description": "Requests a model pool retried on another member. Each is also counted in requestCount. Only one cut off by a timeout carries tokens or cost: an estimate of the input it read." }, "failedRequestCount": { "type": "number", "description": "Requests that failed, including streams that failed after usage came back. Failed-over pool attempts are counted in failedOverCount instead. Rows logged before failures were tracked count as succeeded." }, "chatErrorCount": { "type": "number", "description": "Errors the chat showed for this session's conversation. Read them at GET /api/llm-proxy-logs/sessions/:sessionId/chat-errors." }, "totalInputTokens": { "type": "number" }, "totalOutputTokens": { "type": "number" }, "totalCacheReadTokens": { "type": "number" }, "totalCacheWriteTokens": { "type": "number" }, "totalCost": { "nullable": true, "type": "string" }, "totalBilledCost": { "nullable": true, "type": "string" }, "totalSubscriptionCost": { "nullable": true, "type": "string" }, "totalBaselineCost": { "nullable": true, "type": "string" }, "totalCacheSavings": { "nullable": true, "type": "string" }, "firstRequestTime": { "type": "string", "format": "date-time" }, "lastRequestTime": { "type": "string", "format": "date-time" }, "models": { "type": "array", "items": { "type": "string" } }, "profileId": { "nullable": true, "type": "string" }, "profileName": { "nullable": true, "type": "string" }, "profileAgentType": { "nullable": true, "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "externalAgentIds": { "type": "array", "items": { "type": "string" } }, "externalAgentIdLabels": { "type": "array", "items": { "nullable": true, "type": "string" } }, "authMethods": { "type": "array", "items": { "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] } }, "authenticatedAppNames": { "type": "array", "items": { "type": "string" } }, "userNames": { "type": "array", "items": { "type": "string" } }, "userIds": { "type": "array", "items": { "type": "string" } }, "unattributedReason": { "anyOf": [ { "type": "string", "enum": [ "shared_virtual_key", "provider_key", "client_credentials", "internal", "unknown" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "virtualKeys": { "type": "array", "items": { "$ref": "#/components/schemas/InteractionVirtualKey" } }, "copilotCredentialSources": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] } }, "lastUserMessagePreview": { "nullable": true, "description": "Short preview (max 200 chars) of the session's last user message. Raw request bodies are not returned by this listing.", "type": "string", "maxLength": 200 }, "lastInteractionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastInteractionType": { "nullable": true, "type": "string" }, "contentNotStored": { "type": "boolean", "description": "True when the session's latest turn was logged under the Metadata only Log Content mode, so it has no message preview." }, "conversationTitle": { "nullable": true, "type": "string" }, "claudeCodeTitle": { "nullable": true, "type": "string" }, "connectorName": { "nullable": true, "description": "Name of the knowledge-base connector a knowledge:* session ran for, when exactly one connector owns it.", "type": "string" } }, "required": [ "sessionId", "sessionSource", "source", "sources", "interactionId", "requestCount", "failedOverCount", "failedRequestCount", "chatErrorCount", "totalInputTokens", "totalOutputTokens", "totalCacheReadTokens", "totalCacheWriteTokens", "totalCost", "totalBilledCost", "totalSubscriptionCost", "totalBaselineCost", "totalCacheSavings", "firstRequestTime", "lastRequestTime", "models", "profileId", "profileName", "profileAgentType", "externalAgentIds", "externalAgentIdLabels", "authMethods", "authenticatedAppNames", "userNames", "userIds", "unattributedReason", "virtualKeys", "lastUserMessagePreview", "lastInteractionId", "lastInteractionType", "contentNotStored", "conversationTitle", "claudeCodeTitle", "connectorName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` returns the caller's sessions. `log:admin` includes every session in the active organization.", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/sessions/{sessionId}/lineage": { "get": { "operationId": "getLlmProxyLogSessionLineage", "tags": [ "LLM Proxy Logs" ], "description": "Get a session's fork lineage: the session it forks and the sessions forked from it. A fork is a new client session that starts from another session's history and guardrail state. [`log:read`](/docs/reference/permissions#log:read) covers the caller's own sessions. [`log:admin`](/docs/reference/permissions#log:admin) covers all organization sessions when the client session ID identifies one caller. If multiple callers share that session ID, lineage is ambiguous and the request fails.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "forkedFrom": { "nullable": true, "type": "string" }, "forks": { "type": "array", "items": { "type": "string" } }, "forksTruncated": { "type": "boolean", "description": "True when the session has more forks than the bounded list returned." } }, "required": [ "forkedFrom", "forks", "forksTruncated" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/sessions/{sessionId}/chat-errors": { "get": { "operationId": "getLlmProxyLogSessionChatErrors", "tags": [ "LLM Proxy Logs" ], "description": "Get the errors the chat showed for a session's conversation, oldest first. Empty for sessions that are not chat conversations. [`log:read`](/docs/reference/permissions#log:read) covers the caller's own sessions; [`log:admin`](/docs/reference/permissions#log:admin) covers every session in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } } }, "required": [ "chatErrors" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/sessions/{sessionId}/handoffs": { "get": { "operationId": "getLlmProxyLogSessionHandoffs", "tags": [ "LLM Proxy Logs" ], "description": "Get where a session's work moved between its client and Agent Runtime: the runs it started, or, for a run's own session, the run and the session that started it, with the moves between them. [`log:read`](/docs/reference/permissions#log:read) covers the caller's own runs; [`log:admin`](/docs/reference/permissions#log:admin) covers every run in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "path", "name": "sessionId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "handedTo": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's stable id: its first turn's task id." }, "llmSessionId": { "type": "string", "description": "The run's own LLM session: its workload name." }, "originLlmSessionId": { "type": "string", "description": "The LLM session that started the run." }, "agentName": { "type": "string" }, "title": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" } }, "required": [ "runId", "llmSessionId", "originLlmSessionId", "agentName", "title", "startedAt" ], "additionalProperties": false }, "description": "Runs this session started, oldest first." }, "handedToTruncated": { "type": "boolean", "description": "This session started more runs than `handedTo` lists." }, "handedFrom": { "nullable": true, "description": "When this is a run's own session: that run, with the session that started it.", "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's stable id: its first turn's task id." }, "llmSessionId": { "type": "string", "description": "The run's own LLM session: its workload name." }, "originLlmSessionId": { "type": "string", "description": "The LLM session that started the run." }, "agentName": { "type": "string" }, "title": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" } }, "required": [ "runId", "llmSessionId", "originLlmSessionId", "agentName", "title", "startedAt" ], "additionalProperties": false }, "moves": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "push", "pull", "steer" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpToolCallId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "at": { "description": "When the gateway call that made the move ended.", "type": "string", "format": "date-time" } }, "required": [ "kind", "runId", "mcpToolCallId", "at" ], "additionalProperties": false }, "description": "Moves between the origin session and its runs, oldest first. A move to the side that already holds the work is left out." } }, "required": [ "handedTo", "handedToTruncated", "handedFrom", "moves" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/external-agent-ids": { "get": { "operationId": "getLlmProxyLogExternalAgentIds", "tags": [ "LLM Proxy Logs" ], "description": "Get external agent IDs from visible logs in the active organization. [`log:read`](/docs/reference/permissions#log:read) returns identifiers from the caller's attributed rows; [`log:admin`](/docs/reference/permissions#log:admin) returns identifiers from every row in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) returns identifiers from the caller's rows. [`log:admin`](/docs/reference/permissions#log:admin) includes identifiers from every row in the active organization.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "displayName" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` returns identifiers from the caller's rows. `log:admin` includes identifiers from every row in the active organization.", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/user-ids": { "get": { "operationId": "getLlmProxyLogUserIds", "tags": [ "LLM Proxy Logs" ], "description": "Get users represented in visible logs in the active organization, at most `limit` of them. Without `search` or `ids`, the most active users come first. `search` matches user names; `ids` resolves specific users. [`log:read`](/docs/reference/permissions#log:read) returns only the caller; [`log:admin`](/docs/reference/permissions#log:admin) returns users from every log in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) returns the caller's identity. [`log:admin`](/docs/reference/permissions#log:admin) includes every represented user in the active organization.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "ids", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` returns the caller's identity. `log:admin` includes every represented user in the active organization.", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/{logId}/auto-routing": { "get": { "operationId": "getLlmProxyLogAutoRouting", "tags": [ "LLM Proxy Logs" ], "description": "Get the saved auto-routing decision for an LLM Proxy log. Null means no decision was retained, not that routing was disabled. Does not re-score the request.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "logId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "routerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "segment": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "tierIndex": { "type": "integer", "minimum": -32768, "maximum": 32767 }, "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "propensity": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "u": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "planId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reason": { "type": "string", "enum": [ "planned", "cold_start", "scorer_error", "plan_stale" ] }, "scorerVersionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "features": { "nullable": true, "type": "object", "properties": { "signals": { "type": "object", "properties": { "jev-session": { "type": "object", "properties": { "version": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tier_needed": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "minItems": 3, "maxItems": 3 }, "p_long": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "version", "tier_needed", "p_long" ], "additionalProperties": false } }, "required": [ "jev-session" ], "additionalProperties": false }, "client": { "type": "string" }, "scorerUsage": { "type": "object", "properties": { "inputTokens": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false } }, "required": [ "signals", "client" ], "additionalProperties": false }, "scorerCost": { "nullable": true, "type": "string" }, "featuresSchemaVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "coreVersion": { "type": "string" }, "planFormatVersion": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lambda": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "expectedCostUsd": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "tier": { "type": "string", "enum": [ "fast", "normal", "smart" ] }, "model": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" } }, "required": [ "id", "provider", "modelId" ], "additionalProperties": false }, "router": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "scorerVersion": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "model": { "type": "string" }, "specHash": { "type": "string" } }, "required": [ "id", "name", "model", "specHash" ], "additionalProperties": false } }, "required": [ "id", "routerId", "segment", "tierIndex", "modelId", "propensity", "u", "planId", "reason", "scorerVersionId", "features", "scorerCost", "featuresSchemaVersion", "coreVersion", "planFormatVersion", "lambda", "expectedCostUsd", "createdAt", "tier", "model", "router", "scorerVersion" ], "additionalProperties": false } }, "required": [ "decision" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/llm-proxy-logs/{logId}": { "get": { "operationId": "getLlmProxyLog", "tags": [ "LLM Proxy Logs" ], "description": "Get an LLM Proxy request log by ID. [`log:read`](/docs/reference/permissions#log:read) permits a row attributed to the caller; [`log:admin`](/docs/reference/permissions#log:admin) permits any row in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) permits a row attributed to the caller. [`log:admin`](/docs/reference/permissions#log:admin) permits any row in the active organization.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "logId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OpenAiChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response.compaction" ] }, "created_at": { "type": "number" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "output", "usage" ], "additionalProperties": {} } ] }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "gemini:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "bedrock:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" }, "truncatedFrom": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cohere:embeddings" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/GeminiGenerateContentRequest" }, { "type": "object", "properties": { "input_files": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } ] }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/GeminiGenerateContentRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/GeminiGenerateContentResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "gemini:generateContent" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "anthropic:messages", "github-copilot:messages" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ], "additionalProperties": false } }, "required": [ "toolResult" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } }, "required": [ "name", "inputSchema" ], "additionalProperties": false }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ], "additionalProperties": false } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ], "additionalProperties": false }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ], "additionalProperties": false }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ], "additionalProperties": false } }, "required": [ "jsonSchema" ], "additionalProperties": false } }, "required": [ "type", "structure" ], "additionalProperties": false } }, "additionalProperties": false }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "modelId": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "toolResult": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "image": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "jpeg", "gif", "webp" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "source" ], "additionalProperties": false } }, "required": [ "image" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md" ] }, "name": { "type": "string" }, "source": { "anyOf": [ { "type": "object", "properties": { "bytes": { "type": "string" } }, "required": [ "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "s3Location": { "type": "object", "properties": { "uri": { "type": "string" }, "bucketOwner": { "type": "string" } }, "required": [ "uri" ], "additionalProperties": false } }, "required": [ "s3Location" ], "additionalProperties": false } ] } }, "required": [ "format", "name", "source" ], "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false } ] } }, "status": { "type": "string", "enum": [ "success", "error" ] } }, "required": [ "toolUseId", "content" ], "additionalProperties": false } }, "required": [ "toolResult" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "system": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "guardContent": { "type": "object", "properties": { "text": { "type": "object", "properties": { "text": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string", "enum": [ "grounding_source", "query", "guard_content" ] } } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "guardContent" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string" }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "cachePoint" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] } }, "inferenceConfig": { "type": "object", "properties": { "maxTokens": { "type": "number" }, "temperature": { "type": "number" }, "topP": { "type": "number" }, "stopSequences": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolConfig": { "type": "object", "properties": { "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "toolSpec": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } }, "required": [ "name", "inputSchema" ], "additionalProperties": false }, "cachePoint": { "not": {} } }, "required": [ "toolSpec" ], "additionalProperties": false }, { "type": "object", "properties": { "cachePoint": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "ttl": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "toolSpec": { "not": {} } }, "required": [ "cachePoint" ], "additionalProperties": false } ] } }, "toolChoice": { "anyOf": [ { "type": "object", "properties": { "tool": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "tool" ], "additionalProperties": {} }, { "type": "object", "properties": { "any": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "any" ], "additionalProperties": {} }, { "type": "object", "properties": { "auto": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "auto" ], "additionalProperties": {} } ] } }, "required": [ "tools" ], "additionalProperties": false }, "guardrailConfig": { "type": "object", "properties": { "guardrailIdentifier": { "type": "string" }, "guardrailVersion": { "type": "string" }, "trace": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "guardrailIdentifier", "guardrailVersion" ], "additionalProperties": false }, "additionalModelRequestFields": { "type": "object", "additionalProperties": {} }, "additionalModelResponseFieldPaths": { "type": "array", "items": { "type": "string" } }, "outputConfig": { "type": "object", "properties": { "textFormat": { "type": "object", "properties": { "type": { "type": "string" }, "structure": { "type": "object", "properties": { "jsonSchema": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "schema" ], "additionalProperties": false } }, "required": [ "jsonSchema" ], "additionalProperties": false } }, "required": [ "type", "structure" ], "additionalProperties": false } }, "additionalProperties": false }, "promptVariables": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "json": { "type": "object", "additionalProperties": {} } }, "required": [ "json" ], "additionalProperties": false } ] } }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false }, "requestMetadata": { "type": "object", "additionalProperties": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "modelId" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "$metadata": { "type": "object", "properties": { "httpStatusCode": { "type": "number" }, "requestId": { "type": "string" }, "attempts": { "type": "number" }, "totalRetryDelay": { "type": "number" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "message": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "assistant" ] }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "toolUse": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "name": { "type": "string" }, "input": { "type": "object", "additionalProperties": {} } }, "required": [ "toolUseId", "name", "input" ], "additionalProperties": false } }, "required": [ "toolUse" ], "additionalProperties": false }, { "type": "object", "properties": { "reasoningContent": { "anyOf": [ { "type": "object", "properties": { "reasoningText": { "type": "object", "properties": { "text": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "text" ], "additionalProperties": false } }, "required": [ "reasoningText" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedContent": { "type": "string" } }, "required": [ "redactedContent" ], "additionalProperties": false }, { "type": "object", "properties": { "redactedReasoning": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ], "additionalProperties": false } }, "required": [ "redactedReasoning" ], "additionalProperties": false } ] } }, "required": [ "reasoningContent" ], "additionalProperties": false } ] } } }, "required": [ "role", "content" ], "additionalProperties": false } }, "additionalProperties": false }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered", "malformed_model_output", "malformed_tool_use", "model_context_window_exceeded" ] }, { "type": "string" } ] }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadInputTokens": { "type": "number" }, "cacheWriteInputTokens": { "type": "number" }, "cacheDetails": { "type": "array", "items": { "type": "object", "properties": { "ttl": { "type": "string" }, "inputTokens": { "type": "number" } }, "additionalProperties": false } } }, "required": [ "inputTokens", "outputTokens" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "latencyMs": { "type": "number" } }, "additionalProperties": false }, "additionalModelResponseFields": { "type": "object", "additionalProperties": {} }, "trace": { "type": "object", "properties": { "guardrail": { "type": "object", "properties": { "inputAssessment": { "type": "object", "additionalProperties": {} }, "outputAssessments": { "type": "object", "additionalProperties": {} }, "modelOutput": { "type": "array", "items": { "type": "string" } }, "actionReason": { "type": "string" } }, "additionalProperties": false }, "promptRouter": { "type": "object", "properties": { "invokedModelId": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "performanceConfig": { "type": "object", "properties": { "latency": { "type": "string", "enum": [ "optimized" ] } }, "additionalProperties": false }, "serviceTier": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default", "throughput" ] } }, "additionalProperties": false } }, "required": [ "output", "stopReason", "usage" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "bedrock:converse" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ], "additionalProperties": false } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "thinking": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "type", "thinking", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redacted_thinking" ] }, "data": { "type": "string" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "input": {}, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_use" ] }, "cache_control": { "nullable": true } }, "required": [ "id", "input", "name", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "tool_use_id": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] }, "cache_control": { "nullable": true }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string", "enum": [ "application/pdf" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "media_type": { "type": "string", "enum": [ "text/plain" ] }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type", "url" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "content" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "text", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base64" ] }, "media_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "type", "media_type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string" } }, "required": [ "type", "url" ], "additionalProperties": false } ] }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false } ] } } ] } }, "required": [ "type", "content" ], "additionalProperties": false } ] }, "title": { "nullable": true, "type": "string" }, "context": { "nullable": true, "type": "string" }, "citations": { "nullable": true, "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "cache_control": { "nullable": true } }, "required": [ "type", "source" ], "additionalProperties": false, "description": "Anthropic Messages API request `DocumentBlockParam`. This models a user `content` item with `type: \"document\"` and supports the source union exposed by Anthropic: `Base64PDFSource | PlainTextSource | ContentBlockSource | URLPDFSource`. API reference: https://platform.claude.com/docs/en/api/messages#document_block_param" } ] } } ] }, "is_error": { "type": "boolean" } }, "required": [ "tool_use_id", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_result", "server_tool_use", "web_search_tool_result", "web_fetch_tool_result", "code_execution_tool_result", "bash_code_execution_tool_result", "text_editor_code_execution_tool_result", "tool_search_tool_result", "container_upload" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } } ] }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, "max_tokens": { "type": "number" }, "container": { "nullable": true, "type": "string" }, "context_management": { "nullable": true, "type": "object", "properties": {}, "additionalProperties": {} }, "mcp_servers": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": { "user_id": { "nullable": true, "type": "string" } }, "additionalProperties": {} }, "output_config": { "type": "object", "properties": { "effort": { "nullable": true, "type": "string" }, "format": { "nullable": true, "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ], "additionalProperties": false } }, "additionalProperties": {} }, "service_tier": {}, "speed": { "type": "string", "enum": [ "fast", "standard" ] }, "stop_sequences": { "type": "array", "items": { "type": "string" } }, "stream": { "type": "boolean" }, "system": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "cache_control": { "nullable": true }, "citations": { "nullable": true, "type": "array", "items": {} } }, "required": [ "type", "text" ], "additionalProperties": {} } } ] }, "temperature": { "type": "number" }, "thinking": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enabled" ] }, "budget_tokens": { "type": "number" }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type", "budget_tokens" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "disabled" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "between_tools" ] } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adaptive" ] }, "display": { "nullable": true, "type": "string", "enum": [ "summarized", "omitted", "updates" ] }, "block_binding": { "nullable": true, "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] }, "tool_choice": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auto" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "any" ] }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool" ] }, "name": { "type": "string" }, "disable_parallel_tool_use": { "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false } ] }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "type": { "nullable": true, "type": "string", "enum": [ "custom" ] }, "cache_control": { "nullable": true }, "input_schema": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" } }, "required": [ "name", "input_schema" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "bash" ] }, "type": { "type": "string", "enum": [ "bash_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_editor" ] }, "type": { "type": "string", "enum": [ "text_editor_20250124" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250429" ] }, "cache_control": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "str_replace_based_edit_tool" ] }, "type": { "type": "string", "enum": [ "text_editor_20250728" ] }, "cache_control": { "nullable": true }, "max_characters": { "nullable": true, "type": "number" } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "name": { "type": "string", "enum": [ "web_search" ] }, "type": { "type": "string", "enum": [ "web_search_20250305" ] }, "allowed_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "blocked_domains": { "nullable": true, "type": "array", "items": { "type": "string" } }, "cache_control": { "nullable": true }, "max_uses": { "nullable": true, "type": "number" }, "user_location": { "nullable": true } }, "required": [ "name", "type" ], "additionalProperties": {} }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "anthropic_version": { "type": "string" }, "anthropic_beta": { "type": "array", "items": { "type": "string" } }, "_isStreaming": { "type": "boolean" } }, "required": [ "messages", "max_tokens" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/AnthropicMessagesResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "bedrock:invoke" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/CerebrasChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cerebras:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/MistralChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "mistral:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/PerplexityChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/PerplexityChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/PerplexityChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "perplexity:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/GroqChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "groq:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "xai:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/OpenrouterChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/OpenrouterChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OpenrouterChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openrouter:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/VllmChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/VllmChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/VllmChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "vllm:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/OllamaChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/OllamaChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OllamaChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "ollama:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/OllamaNativeChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/OllamaNativeChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/OllamaNativeChatResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "ollama-native:chat" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/CohereChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/CohereChatRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/CohereChatResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "cohere:chat" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/ZhipuaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/ZhipuaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/ZhipuaiChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "zhipuai:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/DeepSeekChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/DeepSeekChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/DeepSeekChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "deepseek:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "kimi:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "kimi-code:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string" }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "model" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "github-copilot:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "microsoft-365-copilot:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/MinimaxChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/MinimaxChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/MinimaxChatCompletionResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "minimax:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/XaiChatCompletionRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:chatCompletions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" }, "target_language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$" } }, "required": [ "model", "messages" ], "additionalProperties": false, "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ], "additionalProperties": false }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ], "additionalProperties": false } ] } }, "required": [ "type", "name" ], "additionalProperties": false, "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "additionalProperties": false, "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "function" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "additionalProperties": false, "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "additionalProperties": false, "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ], "additionalProperties": false } ] } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "custom" ], "additionalProperties": false, "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ], "additionalProperties": false }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } }, "additionalProperties": false }, "user": { "type": "string" }, "target_language": { "type": "string", "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$" } }, "required": [ "model", "messages" ], "additionalProperties": false, "description": "A bounded realtime audio turn. Translation requires WAV input and target_language; tools are not supported." }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:realtime" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usage_available": { "type": "boolean" }, "cost_available": { "type": "boolean" }, "usage": { "type": "object", "additionalProperties": {} }, "speech_input": { "type": "string" }, "transcript": { "type": "string" }, "audio": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "audio_omitted": { "type": "string", "enum": [ "too_large" ] }, "upload": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "upload_omitted": { "type": "string", "enum": [ "too_large" ] } }, "required": [ "id", "model", "operation", "content_type", "bytes", "usage_available", "cost_available" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:audio" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "response_format": { "type": "string" }, "stream_format": { "type": "string" }, "input_characters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "file": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration_seconds": { "type": "number", "minimum": 0 } }, "required": [ "filename", "mimetype", "size" ], "additionalProperties": false } }, "required": [ "model", "operation" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "speech", "transcriptions", "translations" ] }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usage_available": { "type": "boolean" }, "cost_available": { "type": "boolean" }, "usage": { "type": "object", "additionalProperties": {} }, "speech_input": { "type": "string" }, "transcript": { "type": "string" }, "audio": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "audio_omitted": { "type": "string", "enum": [ "too_large" ] }, "upload": { "type": "object", "properties": { "content_type": { "type": "string" }, "data": { "type": "string" } }, "required": [ "content_type", "data" ], "additionalProperties": false }, "upload_omitted": { "type": "string", "enum": [ "too_large" ] } }, "required": [ "id", "model", "operation", "content_type", "bytes", "usage_available", "cost_available" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:audio" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:images", "openai:images" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "azure:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "perplexity:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {} }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "model", "output" ], "additionalProperties": {} }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "github-copilot:responses" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "$ref": "#/components/schemas/JevDecisionsRequest" }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "$ref": "#/components/schemas/JevDecisionsRequest" }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "$ref": "#/components/schemas/JevDecisionsResponse" }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "jev:decisions" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "turn": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "session": { "type": "object", "additionalProperties": {} }, "input_text": { "type": "string" }, "input_transcript": { "type": "string" } }, "required": [ "model", "turn" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "model": { "type": "string" }, "turn": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "session": { "type": "object", "additionalProperties": {} }, "input_text": { "type": "string" }, "input_transcript": { "type": "string" } }, "required": [ "model", "turn" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "output_transcript": { "type": "string" }, "output_audio": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pcm16" ] }, "sample_rate": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "data": { "type": "string" } }, "required": [ "format", "sample_rate", "data" ], "additionalProperties": false }, "output_audio_omitted": { "type": "string", "enum": [ "too_large" ] }, "output": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "usage": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:realtime" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "profileId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalAgentId": { "nullable": true, "type": "string" }, "runId": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "virtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "passthroughVirtualKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attempt": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "attemptOutcome": { "nullable": true, "type": "string" }, "failureReason": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "boolean" }, "sessionId": { "nullable": true, "type": "string" }, "sessionSource": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "model_router", "opencode:main", "opencode:subagent", "opencode:title", "opencode:compaction", "kilo:main", "kilo:subagent", "kilo:title", "kilo:compaction", "chat", "chat:compaction", "a2a:compaction", "chat:title_generation", "chat:tool_call_repair", "a2a:tool_call_repair", "skill:description_generation", "guardrail:dual_llm", "guardrail:annotator", "guardrail:sanitizer", "guardrail:hitl_summary", "chatops:slack", "chatops:ms-teams", "chatops:telegram", "chatops:jira", "email", "schedule-trigger", "knowledge:embedding", "knowledge:reranker", "knowledge:query-expansion", "knowledge:contextual-retrieval", "knowledge:ocr", "app:llm_complete", "app:recording_enhancement", "tool_search_text:generation" ] }, "authMethod": { "nullable": true, "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "billingMode": { "type": "string", "enum": [ "metered", "subscription" ] }, "authenticatedAppId": { "nullable": true, "type": "string" }, "authenticatedAppName": { "nullable": true, "type": "string" }, "billingTeamId": { "nullable": true, "type": "string" }, "attributionLabels": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "request": { "anyOf": [ { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "query": { "type": "string" }, "content_type": { "type": "string" }, "content_length": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "body": {}, "truncated": { "type": "boolean" } }, "required": [ "method", "path" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "processedRequest": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "query": { "type": "string" }, "content_type": { "type": "string" }, "content_length": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "body": {}, "truncated": { "type": "boolean" } }, "required": [ "method", "path" ], "additionalProperties": false }, { "type": "object", "additionalProperties": {} } ] }, "response": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "content_type": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "body": {}, "truncated": { "type": "boolean" }, "streamed": { "type": "boolean" } }, "required": [ "status", "bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, { "anyOf": [ { "$ref": "#/components/schemas/LogContentNotStored" }, { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolCallBlock": { "nullable": true, "type": "object", "properties": { "reason": { "type": "string" }, "blockedToolCallCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "reason", "blockedToolCallCount" ], "additionalProperties": false }, "type": { "type": "string", "enum": [ "openai:passthrough", "anthropic:passthrough" ] }, "model": { "nullable": true, "type": "string" }, "baselineModel": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokens": { "nullable": true, "description": "Input tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputTokensEstimated": { "type": "boolean", "description": "True when the input token count was estimated locally rather than reported by the provider." }, "outputTokens": { "nullable": true, "description": "Output tokens recorded for this request. Null means unavailable; zero is a recorded zero. The count can be partial if a stream ends early.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheReadTokens": { "nullable": true, "description": "Tokens read from provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWriteTokens": { "nullable": true, "description": "Tokens written to provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cacheWrite1hTokens": { "nullable": true, "description": "Tokens written to a one-hour provider cache. Null means unavailable or not applicable; zero is a recorded zero.", "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "baselineCost": { "nullable": true, "type": "string" }, "cost": { "nullable": true, "type": "string" }, "cacheCost": { "nullable": true, "type": "string" }, "cacheSavings": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "connectorName": { "nullable": true, "type": "string" }, "copilotCredentialSource": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "organization" ] }, "organization": { "nullable": true, "type": "string" }, "organizationName": { "nullable": true, "type": "string" } }, "required": [ "kind", "organization" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personal" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "virtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "passthroughVirtualKey": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InteractionVirtualKey" } ] }, "requestType": { "type": "string", "enum": [ "main", "subagent" ] }, "externalAgentIdLabel": { "nullable": true, "type": "string" } }, "required": [ "id", "profileId", "externalAgentId", "runId", "userId", "serviceAccountId", "virtualKeyId", "passthroughVirtualKeyId", "environmentId", "connectorId", "appId", "providerApiKeyId", "modelPoolId", "attempt", "attemptOutcome", "failureReason", "failed", "sessionId", "sessionSource", "billingMode", "authenticatedAppId", "authenticatedAppName", "billingTeamId", "attributionLabels", "request", "response", "type", "model", "baselineModel", "durationMs", "inputTokens", "inputTokensEstimated", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "cacheWrite1hTokens", "baselineCost", "cost", "cacheCost", "cacheSavings", "createdAt" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` permits a row attributed to the caller. `log:admin` permits any row in the active organization.", "permissions": [ "log:read" ] } } }, "/api/internal_mcp_catalog/{id}/transfer-ownership": { "post": { "operationId": "transferMcpCatalogOwnership", "tags": [ "Ownership" ], "description": "Transfer ownership to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog": { "get": { "operationId": "getInternalMcpCatalog", "tags": [ "MCP Catalog" ], "description": "Get all Internal MCP catalog items\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "includeApps", "required": false }, { "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. `deleted` lists only soft-deleted catalog items you can delete." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "toolPrefix": { "nullable": true, "type": "string" }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type", "required" ], "additionalProperties": false } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "deploymentName": { "nullable": true, "type": "string" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefault" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ], "additionalProperties": false } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ], "additionalProperties": false } }, "dockerImage": { "type": "string" }, "serviceAccount": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "number" }, "httpPath": { "type": "string" }, "nodePort": { "type": "number" }, "imagePullSecrets": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ], "additionalProperties": false } ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string" } }, "additionalProperties": false }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigField" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ], "additionalProperties": false }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "catalogItemApprovalStatus": { "nullable": true, "type": "string" }, "catalogItemApprovalReason": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedBy": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "alertMutes": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } }, "toolCount": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "providesUi": { "type": "boolean" }, "skillCount": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "providesSkills": { "type": "boolean" }, "appId": { "nullable": true, "type": "string" }, "appEnabled": { "nullable": true, "type": "boolean" }, "imageApprovalRequired": { "type": "boolean" }, "effectiveActions": { "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "id", "name", "toolPrefix", "version", "description", "instructions", "repository", "installationCommand", "requiresAuth", "authDescription", "authFields", "serverType", "multitenant", "deploymentName", "dynamicConnectionMcpServerId", "serverUrl", "docsUrl", "clientSecretId", "localConfigSecretId", "localConfig", "desktopConfig", "deploymentSpecYaml", "userConfig", "oauthConfig", "enterpriseManagedConfig", "awsIamConfig", "icon", "organizationId", "authorId", "scope", "clonedFrom", "environmentId", "catalogReinstallRequired", "catalogItemApprovalStatus", "catalogItemApprovalReason", "catalogItemApprovalReviewedBy", "catalogItemApprovalReviewedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "labels", "teams", "toolCount", "skillCount" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createInternalMcpCatalogItem", "tags": [ "MCP Catalog" ], "description": "Create a new Internal MCP catalog item\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:create`](/docs/reference/permissions#mcpRegistry:create): Add servers to the MCP registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type" ] } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string", "format": "uri" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "pattern": "^[-._a-zA-Z][-._a-zA-Z0-9]*$" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefaultInput" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ] } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ] } }, "dockerImage": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "httpPath": { "type": "string", "format": "starts_with", "pattern": "^\\/.*" }, "nodePort": { "type": "number" }, "serviceAccount": { "type": "string" }, "imagePullSecrets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } } }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigFieldInput" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ] }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "clientSecretOverride": { "type": "string" }, "privateKeyPemOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ] }, "icon": { "nullable": true, "type": "string" }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ] } }, "scope": { "not": {} }, "teams": { "not": {} }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name", "serverType" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "toolPrefix": { "nullable": true, "type": "string" }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type", "required" ], "additionalProperties": false } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "deploymentName": { "nullable": true, "type": "string" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefault" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ], "additionalProperties": false } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ], "additionalProperties": false } }, "dockerImage": { "type": "string" }, "serviceAccount": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "number" }, "httpPath": { "type": "string" }, "nodePort": { "type": "number" }, "imagePullSecrets": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ], "additionalProperties": false } ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string" } }, "additionalProperties": false }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigField" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ], "additionalProperties": false }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "catalogItemApprovalStatus": { "nullable": true, "type": "string" }, "catalogItemApprovalReason": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedBy": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "name", "toolPrefix", "version", "description", "instructions", "repository", "installationCommand", "requiresAuth", "authDescription", "authFields", "serverType", "multitenant", "deploymentName", "dynamicConnectionMcpServerId", "serverUrl", "docsUrl", "clientSecretId", "localConfigSecretId", "localConfig", "desktopConfig", "deploymentSpecYaml", "userConfig", "oauthConfig", "enterpriseManagedConfig", "awsIamConfig", "icon", "organizationId", "authorId", "scope", "clonedFrom", "environmentId", "catalogReinstallRequired", "catalogItemApprovalStatus", "catalogItemApprovalReason", "catalogItemApprovalReviewedBy", "catalogItemApprovalReviewedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "labels", "teams" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:create" ] } } }, "/api/internal_mcp_catalog/registry/search": { "post": { "operationId": "searchMcpRegistry", "tags": [ "MCP Catalog" ], "description": "One page of the MCP registry list, filtered, ordered and counted on the server\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sortBy": { "type": "string", "enum": [ "name", "createdAt", "toolCount", "attention", "issueAge" ] }, "sortDirection": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "search": { "type": "string", "maxLength": 256 }, "searchDescriptions": { "description": "Match the search against descriptions too, not only names.", "type": "boolean" }, "labels": { "type": "object", "additionalProperties": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 256 } } }, "access": { "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "sharedWith": { "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering.", "minItems": 1, "type": "array", "items": { "type": "string" } }, "owner": { "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering.", "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "environmentIds": { "description": "Items in these environments. An empty list matches nothing; omit it for every environment.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "authorIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "authorServiceAccountIds": { "description": "Items created by these service accounts. With authorIds, either matches.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "installState": { "description": "Installed: the caller can see and use an install of the item. Omit for both.", "type": "string", "enum": [ "installed", "not-installed" ] }, "catalogIds": { "description": "Only these items. An empty list matches nothing; omit it for every item.", "maxItems": 10000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeBuiltIn": { "description": "Also list the built-in MCP server entry.", "type": "boolean" }, "includeDefaultEnvironment": { "description": "With environmentIds: also match items in the Default environment (no environment).", "type": "boolean" }, "includeApps": { "description": "Also list app backing entries (with appId and appEnabled). Needs app:read; ignored without it.", "type": "boolean" }, "rankTiers": { "description": "Catalog ids ranked by the caller, tier by tier, for the attention and issueAge orders. Unranked items follow the last tier. These two orders always put the first tier first; sortDirection does not apply to them.", "maxItems": 1000, "type": "array", "items": { "maxItems": 10000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "toolCount": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skillCount": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "providesUi": { "type": "boolean" }, "providesSkills": { "type": "boolean" }, "catalogReinstallRequired": { "type": "boolean" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string" }, "appEnabled": { "nullable": true, "type": "boolean" }, "docsUrl": { "nullable": true, "type": "string" }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "iconUrl": { "nullable": true, "type": "string" }, "alertMutes": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } }, "effectiveActions": { "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "imageApprovalRequired": { "type": "boolean" }, "bindsCredential": { "type": "boolean" }, "enterpriseManaged": { "type": "boolean" }, "setupNeeds": { "type": "object", "properties": { "signIn": { "type": "boolean" }, "settings": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "signIn", "settings" ], "additionalProperties": false }, "install": { "type": "object", "properties": { "visibleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "installedForViewer": { "type": "boolean" }, "primaryServerId": { "nullable": true, "type": "string" } }, "required": [ "visibleCount", "installedForViewer", "primaryServerId" ], "additionalProperties": false } }, "required": [ "id", "name", "serverType", "multitenant", "scope", "authorId", "description", "labels", "teams", "environmentId", "toolCount", "skillCount", "catalogReinstallRequired", "dynamicConnectionMcpServerId", "docsUrl", "desktopConfig", "icon", "iconUrl", "alertMutes", "effectiveActions", "imageApprovalRequired", "bindsCredential", "enterpriseManaged", "setupNeeds", "install" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "selectableTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "installs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "alertMutes": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } }, "canUseCredential": { "type": "boolean", "description": "Whether the caller may present this install's stored credential to the upstream — their own connection, or one shared with them. False for another member's personal connection, which the listing still returns to installation admins so they can manage it." } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt", "alertMutes", "canUseCredential" ], "additionalProperties": false } }, "attentionTiers": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } }, "required": [ "data", "pagination", "selectableTotal", "installs" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/registry/search/ids": { "post": { "operationId": "searchMcpRegistryIds", "tags": [ "MCP Catalog" ], "description": "Every registry item matching the filters that has an install the caller can see, with the install that stands in for it. Backs selecting every matching row.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sortBy": { "type": "string", "enum": [ "name", "createdAt", "toolCount", "attention", "issueAge" ] }, "sortDirection": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "search": { "type": "string", "maxLength": 256 }, "searchDescriptions": { "description": "Match the search against descriptions too, not only names.", "type": "boolean" }, "labels": { "type": "object", "additionalProperties": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 256 } } }, "access": { "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "sharedWith": { "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering.", "minItems": 1, "type": "array", "items": { "type": "string" } }, "owner": { "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering.", "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "environmentIds": { "description": "Items in these environments. An empty list matches nothing; omit it for every environment.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "authorIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "authorServiceAccountIds": { "description": "Items created by these service accounts. With authorIds, either matches.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "installState": { "description": "Installed: the caller can see and use an install of the item. Omit for both.", "type": "string", "enum": [ "installed", "not-installed" ] }, "catalogIds": { "description": "Only these items. An empty list matches nothing; omit it for every item.", "maxItems": 10000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeBuiltIn": { "description": "Also list the built-in MCP server entry.", "type": "boolean" }, "includeDefaultEnvironment": { "description": "With environmentIds: also match items in the Default environment (no environment).", "type": "boolean" }, "includeApps": { "description": "Also list app backing entries (with appId and appEnabled). Needs app:read; ignored without it.", "type": "boolean" }, "rankTiers": { "description": "Catalog ids ranked by the caller, tier by tier, for the attention and issueAge orders. Unranked items follow the last tier. These two orders always put the first tier first; sortDirection does not apply to them.", "maxItems": 1000, "type": "array", "items": { "maxItems": 10000, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "primaryServerId": { "type": "string" } }, "required": [ "id", "name", "primaryServerId" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "data", "truncated" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/registry/issue-index": { "get": { "operationId": "getMcpRegistryIssueIndex", "tags": [ "MCP Catalog" ], "description": "Every catalog item and install the caller can see, reduced to what the registry's issue rule and filter options read\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "toolPrefix": { "type": "string" }, "dynamicConnectionMcpServerId": { "type": "string" }, "environmentId": { "type": "string" }, "authorId": { "type": "string" }, "createdByServiceAccountId": { "type": "string" }, "authorName": { "type": "string" }, "icon": { "type": "string" }, "iconUrl": { "type": "string" }, "alertMutes": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } } }, "required": [ "id", "name", "serverType", "multitenant" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "ownerId": { "type": "string" }, "teamId": { "type": "string" }, "localInstallationError": { "type": "string" }, "oauthRefreshError": { "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "type": "string" }, "oauthRefreshErrorDescription": { "type": "string" }, "oauthRefreshFailedAt": { "type": "string", "format": "date-time" }, "canUseCredential": { "type": "boolean" }, "alertMutes": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } } }, "required": [ "id", "name", "catalogId", "scope", "localInstallationStatus", "updatedAt", "canUseCredential" ], "additionalProperties": false } } }, "required": [ "catalogItems", "servers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/icon": { "get": { "operationId": "getInternalMcpCatalogIcon", "tags": [ "MCP Catalog" ], "description": "The image icon of a catalog item, for list views that do not carry icon data inline\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "v", "required": false, "description": "Content version; any value." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/alert-mutes/{kind}": { "put": { "operationId": "muteMcpCatalogAlert", "tags": [ "MCP Catalog" ], "description": "Dismiss one catalog-level MCP alert for the calling user only. The fingerprint pins it to one failure episode.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issueFingerprint": { "type": "string", "minLength": 1, "maxLength": 500 }, "reason": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "issueFingerprint" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } }, "delete": { "operationId": "unmuteMcpCatalogAlert", "tags": [ "MCP Catalog" ], "description": "Restore one dismissed catalog-level MCP alert to the calling user's view.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "in": "query", "name": "issueFingerprint", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/internal_mcp_catalog/{id}": { "get": { "operationId": "getInternalMcpCatalogItem", "tags": [ "MCP Catalog" ], "description": "Get Internal MCP catalog item by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "listedOnly", "required": false, "description": "Answer 404 for hidden runtime variants (Playwright per-environment rows); app backings are still returned. Default false." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "toolPrefix": { "nullable": true, "type": "string" }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type", "required" ], "additionalProperties": false } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "deploymentName": { "nullable": true, "type": "string" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefault" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ], "additionalProperties": false } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ], "additionalProperties": false } }, "dockerImage": { "type": "string" }, "serviceAccount": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "number" }, "httpPath": { "type": "string" }, "nodePort": { "type": "number" }, "imagePullSecrets": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ], "additionalProperties": false } ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string" } }, "additionalProperties": false }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigField" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ], "additionalProperties": false }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "catalogItemApprovalStatus": { "nullable": true, "type": "string" }, "catalogItemApprovalReason": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedBy": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "toolCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "skillCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "providesUi": { "type": "boolean" }, "providesSkills": { "type": "boolean" }, "effectiveActions": { "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "imageApprovalRequired": { "type": "boolean" } }, "required": [ "id", "name", "toolPrefix", "version", "description", "instructions", "repository", "installationCommand", "requiresAuth", "authDescription", "authFields", "serverType", "multitenant", "deploymentName", "dynamicConnectionMcpServerId", "serverUrl", "docsUrl", "clientSecretId", "localConfigSecretId", "localConfig", "desktopConfig", "deploymentSpecYaml", "userConfig", "oauthConfig", "enterpriseManagedConfig", "awsIamConfig", "icon", "organizationId", "authorId", "scope", "clonedFrom", "environmentId", "catalogReinstallRequired", "catalogItemApprovalStatus", "catalogItemApprovalReason", "catalogItemApprovalReviewedBy", "catalogItemApprovalReviewedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "labels", "teams" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateInternalMcpCatalogItem", "tags": [ "MCP Catalog" ], "description": "Update an Internal MCP catalog item\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type" ] } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string", "format": "uri" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "pattern": "^[-._a-zA-Z][-._a-zA-Z0-9]*$" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefaultInput" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ] } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ] } }, "dockerImage": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "integer", "minimum": 1, "maximum": 65535 }, "httpPath": { "type": "string", "format": "starts_with", "pattern": "^\\/.*" }, "nodePort": { "type": "number" }, "serviceAccount": { "type": "string" }, "imagePullSecrets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ] }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } } }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigFieldInput" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ] }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "clientSecretOverride": { "type": "string" }, "privateKeyPemOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ] }, "icon": { "nullable": true, "type": "string" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ] } }, "scope": { "not": {} }, "teams": { "not": {} }, "multitenant": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "toolPrefix": { "nullable": true, "type": "string" }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type", "required" ], "additionalProperties": false } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "deploymentName": { "nullable": true, "type": "string" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefault" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ], "additionalProperties": false } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ], "additionalProperties": false } }, "dockerImage": { "type": "string" }, "serviceAccount": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "number" }, "httpPath": { "type": "string" }, "nodePort": { "type": "number" }, "imagePullSecrets": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ], "additionalProperties": false } ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string" } }, "additionalProperties": false }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigField" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ], "additionalProperties": false }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "catalogItemApprovalStatus": { "nullable": true, "type": "string" }, "catalogItemApprovalReason": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedBy": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "name", "toolPrefix", "version", "description", "instructions", "repository", "installationCommand", "requiresAuth", "authDescription", "authFields", "serverType", "multitenant", "deploymentName", "dynamicConnectionMcpServerId", "serverUrl", "docsUrl", "clientSecretId", "localConfigSecretId", "localConfig", "desktopConfig", "deploymentSpecYaml", "userConfig", "oauthConfig", "enterpriseManagedConfig", "awsIamConfig", "icon", "organizationId", "authorId", "scope", "clonedFrom", "environmentId", "catalogReinstallRequired", "catalogItemApprovalStatus", "catalogItemApprovalReason", "catalogItemApprovalReviewedBy", "catalogItemApprovalReviewedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "labels", "teams" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteInternalMcpCatalogItem", "tags": [ "MCP Catalog" ], "description": "Delete an Internal MCP catalog item\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/credential-preflight": { "get": { "operationId": "getInternalMcpCatalogCredentialPreflight", "tags": [ "MCP Catalog" ], "description": "List the saved credentials that would stop the caller installing this MCP server, and why\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "object", "properties": { "envKey": { "type": "string" }, "credentialId": { "type": "string" }, "credentialName": { "type": "string" }, "reason": { "type": "string", "enum": [ "no_access", "not_connected", "not_set_up", "personal_only" ] } }, "required": [ "envKey", "credentialId", "credentialName", "reason" ], "additionalProperties": false } } }, "required": [ "blockers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/tools": { "get": { "operationId": "getInternalMcpCatalogToolsBatch", "tags": [ "MCP Catalog" ], "description": "Get id/name/catalog for every listable tool across all catalog items the caller can see, in one request. Backs the tool pickers, which previously issued one request per catalog item.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "catalogId": { "type": "string" } }, "required": [ "id", "name", "catalogId" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/tools": { "get": { "operationId": "getInternalMcpCatalogTools", "tags": [ "MCP Catalog" ], "description": "Get tools for a catalog item (including builtin Archestra tools)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": "full", "type": "string", "enum": [ "full", "picker" ] }, "in": "query", "name": "view", "required": false, "description": "Picker metadata excludes parameter bodies and assigned-agent lists." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "group": { "nullable": true, "type": "string" }, "assignedAgentCount": { "type": "number" }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "parameters", "createdAt", "group", "assignedAgentCount", "assignedAgents" ], "additionalProperties": false } }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "group": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "description", "createdAt", "group" ], "additionalProperties": false } } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/reinstall": { "post": { "operationId": "reinstallInternalMcpCatalogItem", "tags": [ "MCP Catalog" ], "description": "Reinstall the shared K8s Deployment for a multi-tenant local catalog and cascade tool sync to every install.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/refresh-image": { "post": { "operationId": "refreshInternalMcpCatalogImage", "tags": [ "MCP Catalog" ], "description": "Restart all local MCP server pods for a catalog so Kubernetes pulls the current configured image. Fan-out restarts are best effort: the request succeeds when at least one target restarts successfully, while failed installs are marked with their own error status.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/pending-image-approval": { "get": { "operationId": "listPendingImageApprovalCatalogItems", "tags": [ "MCP Catalog" ], "description": "List local catalog items in the org whose custom image is awaiting admin approval (blocked by the target environment's trusted image registries).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:update`](/docs/reference/permissions#mcpServerInstallation:update): Modify installed MCP server configuration", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "toolPrefix": { "nullable": true, "type": "string" }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type", "required" ], "additionalProperties": false } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "deploymentName": { "nullable": true, "type": "string" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefault" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ], "additionalProperties": false } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ], "additionalProperties": false } }, "dockerImage": { "type": "string" }, "serviceAccount": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "number" }, "httpPath": { "type": "string" }, "nodePort": { "type": "number" }, "imagePullSecrets": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ], "additionalProperties": false } ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string" } }, "additionalProperties": false }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigField" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ], "additionalProperties": false }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "catalogItemApprovalStatus": { "nullable": true, "type": "string" }, "catalogItemApprovalReason": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedBy": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "name", "toolPrefix", "version", "description", "instructions", "repository", "installationCommand", "requiresAuth", "authDescription", "authFields", "serverType", "multitenant", "deploymentName", "dynamicConnectionMcpServerId", "serverUrl", "docsUrl", "clientSecretId", "localConfigSecretId", "localConfig", "desktopConfig", "deploymentSpecYaml", "userConfig", "oauthConfig", "enterpriseManagedConfig", "awsIamConfig", "icon", "organizationId", "authorId", "scope", "clonedFrom", "environmentId", "catalogReinstallRequired", "catalogItemApprovalStatus", "catalogItemApprovalReason", "catalogItemApprovalReviewedBy", "catalogItemApprovalReviewedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "labels", "teams" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:update" ] } } }, "/api/internal_mcp_catalog/{id}/approve": { "post": { "operationId": "approveCatalogItemImage", "tags": [ "MCP Catalog" ], "description": "Approve a local catalog item's image so its installs proceed. Requires mcpServerInstallation:admin.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:update`](/docs/reference/permissions#mcpServerInstallation:update): Modify installed MCP server configuration", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "toolPrefix": { "nullable": true, "type": "string" }, "version": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "instructions": { "nullable": true, "type": "string" }, "repository": { "nullable": true, "type": "string" }, "installationCommand": { "nullable": true, "type": "string" }, "requiresAuth": { "type": "boolean" }, "authDescription": { "nullable": true, "type": "string" }, "authFields": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "default": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "name", "label", "type", "required" ], "additionalProperties": false } }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "multitenant": { "type": "boolean" }, "deploymentName": { "nullable": true, "type": "string" }, "dynamicConnectionMcpServerId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverUrl": { "nullable": true, "type": "string" }, "docsUrl": { "nullable": true, "type": "string" }, "clientSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfigSecretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "localConfig": { "nullable": true, "type": "object", "properties": { "command": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "plain_text", "secret", "boolean", "number" ] }, "value": { "type": "string" }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "credentialScope": { "type": "string", "enum": [ "personal", "organization" ] }, "promptOnInstallation": { "type": "boolean" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": { "allOf": [ { "$ref": "#/components/schemas/LocalConfigEnvironmentDefault" } ] }, "mounted": { "type": "boolean" } }, "required": [ "key", "type", "promptOnInstallation" ], "additionalProperties": false } }, "envFrom": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "configMap" ] }, "name": { "type": "string", "minLength": 1 }, "prefix": { "type": "string" } }, "required": [ "type", "name" ], "additionalProperties": false } }, "dockerImage": { "type": "string" }, "serviceAccount": { "type": "string" }, "transportType": { "type": "string", "enum": [ "stdio", "streamable-http" ] }, "httpPort": { "type": "number" }, "httpPath": { "type": "string" }, "nodePort": { "type": "number" }, "imagePullSecrets": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "enum": [ "existing" ] }, "name": { "type": "string", "minLength": 1 } }, "required": [ "source", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "credentials" ] }, "server": { "type": "string", "minLength": 1 }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" }, "email": { "type": "string" } }, "required": [ "source", "server", "username" ], "additionalProperties": false } ] } ] } }, "imagePullPolicy": { "type": "string", "enum": [ "Always", "IfNotPresent", "Never" ] }, "runtimeTier": { "type": "string" } }, "additionalProperties": false }, "desktopConfig": { "nullable": true, "type": "object", "properties": { "command": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 4096 }, "url": { "nullable": true, "type": "string", "maxLength": 4096 } }, "additionalProperties": false }, "deploymentSpecYaml": { "nullable": true, "type": "string" }, "userConfig": { "nullable": true, "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserConfigField" } }, "oauthConfig": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "server_url": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "client_credentials" ] }, "auth_server_url": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "resource_metadata_url": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "audience": { "type": "string" }, "resource": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "well_known_url": { "type": "string" }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "supports_resource_metadata": { "type": "boolean" }, "additional_scopes": { "type": "array", "items": { "type": "string" } }, "generic_oauth": { "type": "boolean" }, "token_endpoint": { "type": "string" }, "access_token_env_var": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "requires_proxy": { "type": "boolean" }, "provider_name": { "type": "string" }, "browser_auth": { "type": "boolean" }, "streamable_http_url": { "type": "string" }, "streamable_http_port": { "type": "number" } }, "required": [ "name", "server_url", "client_id", "redirect_uris", "scopes", "default_scopes", "supports_resource_metadata" ], "additionalProperties": false }, "enterpriseManagedConfig": { "nullable": true, "type": "object", "properties": { "identityProviderId": { "type": "string" }, "assertionMode": { "type": "string", "enum": [ "exchange", "passthrough" ] }, "resourceType": { "type": "string", "enum": [ "mcp", "oauth_protected_resource", "secret", "service_account", "custom_http" ] }, "resourceIdentifier": { "type": "string" }, "requestedIssuer": { "type": "string" }, "requestedCredentialType": { "type": "string", "enum": [ "id_jag", "bearer_token", "secret", "service_account", "opaque_json" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "audience": { "type": "string" }, "clientIdOverride": { "type": "string" }, "privateKeyIdOverride": { "type": "string" }, "tokenInjectionMode": { "type": "string", "enum": [ "authorization_bearer", "raw_authorization", "header", "env", "body_field" ] }, "headerName": { "type": "string" }, "envVarName": { "type": "string" }, "bodyFieldName": { "type": "string" }, "responseFieldPath": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "fail_closed", "fallback_to_dynamic", "fallback_to_static" ] }, "cacheTtlSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "awsIamConfig": { "nullable": true, "type": "object", "properties": { "roleArn": { "type": "string", "pattern": "^arn:aws[a-z-]*:iam::\\d{12}:role\\/[\\w+=,.@/-]{1,512}$" }, "region": { "type": "string", "pattern": "^[a-z]{2}(-[a-z]+)+-\\d{1,2}$" }, "service": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" }, "audience": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "roleArn", "region", "service" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clonedFrom": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogReinstallRequired": { "type": "boolean" }, "catalogItemApprovalStatus": { "nullable": true, "type": "string" }, "catalogItemApprovalReason": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedBy": { "nullable": true, "type": "string" }, "catalogItemApprovalReviewedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "key", "value" ], "additionalProperties": false } }, "teams": { "default": [], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "level": { "type": "string", "enum": [ "use", "write" ] } }, "required": [ "id", "name", "level" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "required": [ "id", "name", "toolPrefix", "version", "description", "instructions", "repository", "installationCommand", "requiresAuth", "authDescription", "authFields", "serverType", "multitenant", "deploymentName", "dynamicConnectionMcpServerId", "serverUrl", "docsUrl", "clientSecretId", "localConfigSecretId", "localConfig", "desktopConfig", "deploymentSpecYaml", "userConfig", "oauthConfig", "enterpriseManagedConfig", "awsIamConfig", "icon", "organizationId", "authorId", "scope", "clonedFrom", "environmentId", "catalogReinstallRequired", "catalogItemApprovalStatus", "catalogItemApprovalReason", "catalogItemApprovalReviewedBy", "catalogItemApprovalReviewedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "labels", "teams" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:update" ] } } }, "/api/internal_mcp_catalog/by-name/{name}": { "delete": { "operationId": "deleteInternalMcpCatalogItemByName", "tags": [ "MCP Catalog" ], "description": "Delete an Internal MCP catalog item by name\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/restore": { "post": { "operationId": "restoreInternalMcpCatalogItem", "tags": [ "MCP Catalog" ], "description": "Restore a soft-deleted Internal MCP catalog item and its cascaded installs and tools (flag-only reinstall).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/internal_mcp_catalog/{id}/deployment-yaml-preview": { "get": { "operationId": "getDeploymentYamlPreview", "tags": [ "MCP Catalog" ], "description": "Generate a deployment YAML template preview. Requires configure-deployment-spec on this MCP registry entry.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "yaml": { "type": "string" } }, "required": [ "yaml" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/internal_mcp_catalog/validate-deployment-yaml": { "post": { "operationId": "validateDeploymentYaml", "tags": [ "MCP Catalog" ], "description": "Validate a deployment YAML template. Requires configure-deployment-spec on the supplied catalogId, or on all MCP registry entries when catalogId is omitted.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "yaml": { "type": "string", "minLength": 1 } }, "required": [ "yaml" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "errors", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/internal_mcp_catalog/{id}/reset-deployment-yaml": { "post": { "operationId": "resetDeploymentYaml", "tags": [ "MCP Catalog" ], "description": "Reset the deployment YAML to default by clearing the custom YAML. Requires configure-deployment-spec on this MCP registry entry.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "yaml": { "type": "string" } }, "required": [ "yaml" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/k8s/image-pull-secrets": { "get": { "operationId": "getK8sImagePullSecrets", "tags": [ "MCP Catalog" ], "description": "List Kubernetes docker-registry secrets available for imagePullSecrets\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "registryServers": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "registryServers" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/internal_mcp_catalog/labels/keys": { "get": { "operationId": "getInternalMcpCatalogLabelKeys", "tags": [ "MCP Catalog" ], "description": "Get all label keys used by catalog items\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/internal_mcp_catalog/labels/values": { "get": { "operationId": "getInternalMcpCatalogLabelValues", "tags": [ "MCP Catalog" ], "description": "Get all label values for catalog items\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/invitation/{id}/check": { "get": { "operationId": "checkInvitation", "tags": [ "Invitation" ], "description": "Check if an invitation is valid and whether the user exists\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "organizationId": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "nullable": true, "type": "string" } }, "required": [ "id", "email", "organizationId", "status", "expiresAt" ], "additionalProperties": false }, "userExists": { "type": "boolean" } }, "required": [ "invitation", "userExists" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/jev/decisions": { "post": { "operationId": "jevDecisionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Request decisions from Jev (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JevDecisionsRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JevDecisionsResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/jev/{agentId}/decisions": { "post": { "operationId": "jevDecisionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Request decisions from Jev for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JevDecisionsRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JevDecisionsResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/k8s/capabilities": { "get": { "operationId": "getK8sCapabilities", "tags": [ "Organization" ], "description": "Inspect Kubernetes capabilities available to Archestra.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:update`](/docs/reference/permissions#environment:update): Modify deployment environments, including the org default environment", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "networkPolicy": { "type": "object", "properties": { "kubernetesNetworkPolicy": { "type": "boolean" }, "ciliumNetworkPolicy": { "type": "boolean" }, "gkeFqdnNetworkPolicy": { "type": "boolean" }, "awsApplicationNetworkPolicy": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "cilium", "gke-fqdn", "aws-application-network-policy", "kubernetes", "none" ] }, "supportsFqdn": { "type": "boolean" }, "supportsHttpMethods": { "type": "boolean" }, "message": { "nullable": true, "type": "string" }, "enforcementSource": { "type": "string", "enum": [ "probe", "api-discovery" ] }, "enforcementStatus": { "type": "string", "enum": [ "verified-enforced", "verified-not-enforced", "unknown" ] }, "probe": { "type": "string", "enum": [ "enforced", "not-enforced", "inconclusive", "absent" ] }, "probedAt": { "nullable": true, "type": "string" } }, "required": [ "kubernetesNetworkPolicy", "ciliumNetworkPolicy", "gkeFqdnNetworkPolicy", "awsApplicationNetworkPolicy", "provider", "supportsFqdn", "supportsHttpMethods", "message", "enforcementSource", "enforcementStatus", "probe", "probedAt" ], "additionalProperties": false }, "agentSandbox": { "type": "object", "properties": { "installed": { "type": "boolean" }, "missingResources": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "installed", "missingResources", "message" ], "additionalProperties": false } }, "required": [ "networkPolicy", "agentSandbox" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:update" ] } } }, "/v1/kimi-code/chat/completions": { "post": { "operationId": "kimiCodeChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Kimi Code (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/kimi-code/{agentId}/chat/completions": { "post": { "operationId": "kimiCodeChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Kimi Code for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/kimi/chat/completions": { "post": { "operationId": "kimiChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Kimi (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/kimi/{agentId}/chat/completions": { "post": { "operationId": "kimiChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Kimi for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/knowledge-bases/labels/keys": { "get": { "operationId": "knowledgeBaseLabelKeys", "tags": [ "Knowledge Bases" ], "description": "Get all label keys used by knowledge bases\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-bases/labels/values": { "get": { "operationId": "knowledgeBaseLabelValues", "tags": [ "Knowledge Bases" ], "description": "Get all label values used by knowledge bases\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-base-connectors/labels/keys": { "get": { "operationId": "connectorLabelKeys", "tags": [ "Knowledge Bases" ], "description": "Get all label keys used by knowledge connectors\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-base-connectors/labels/values": { "get": { "operationId": "connectorLabelValues", "tags": [ "Knowledge Bases" ], "description": "Get all label values used by knowledge connectors\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-bases": { "get": { "operationId": "getKnowledgeBases", "tags": [ "Knowledge Bases" ], "description": "List all knowledge bases for the organization. `status=deleted` lists the soft-deleted ones instead — the trash view, which requires [`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete). Search and pagination behave identically on both slices, but the deleted slice carries identity only: `connectors` and `assignedAgents` come back empty and `totalDocsIndexed` zero, since those links resolve to nothing while the knowledge base is in the trash.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "teamIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "authorIds", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "excludeAuthorIds", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonal", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. `deleted` lists soft-deleted knowledge bases and requires [`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete)." }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "maxItems": 250, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false, "description": "Only these knowledge bases (comma-separated IDs, at most 250), such as the ones an agent uses. All of them come back in one page; `limit` and `offset` do not apply." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeAssignedAgents", "required": false, "description": "Attach each row's assigned agents (default true). False returns an empty `assignedAgents` array, meaning 'not requested'; `assignedAgentCount` is returned either way." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "org-wide", "team-scoped" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "uploadedFilesEnvironmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] } }, "required": [ "id", "name", "connectorType" ], "additionalProperties": false } }, "totalDocsIndexed": { "type": "number" }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "assignedAgentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "status", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels", "connectors", "totalDocsIndexed", "assignedAgents", "assignedAgentCount" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "post": { "operationId": "createKnowledgeBase", "tags": [ "Knowledge Bases" ], "description": "Create a new knowledge base\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:create`](/docs/reference/permissions#knowledgeSource:create): Create Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "org-wide", "team-scoped" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "uploadedFilesEnvironmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "status", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:create" ] } } }, "/api/knowledge-bases/{id}": { "get": { "operationId": "getKnowledgeBase", "tags": [ "Knowledge Bases" ], "description": "Get a knowledge base by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "org-wide", "team-scoped" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "uploadedFilesEnvironmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "status", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "put": { "operationId": "updateKnowledgeBase", "tags": [ "Knowledge Bases" ], "description": "Update a knowledge base\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "nullable": true, "type": "string" }, "uploadedFilesEnvironmentId": { "description": "Environment for this knowledge base's indexed uploaded files. Requires uploaded files to have been indexed; omit to leave it unchanged.", "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "visibility": { "not": {} }, "teamIds": { "not": {} } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "org-wide", "team-scoped" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "uploadedFilesEnvironmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "status", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } }, "delete": { "operationId": "deleteKnowledgeBase", "tags": [ "Knowledge Bases" ], "description": "Delete a knowledge base and remove its connector assignments\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-bases/bulk": { "delete": { "operationId": "bulkDeleteKnowledgeBases", "tags": [ "Knowledge Bases" ], "description": "Soft-delete several knowledge bases in one request, removing their connector assignments. Ids the caller cannot see are reported in `failed` and leave the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-bases/{id}/restore": { "post": { "operationId": "restoreKnowledgeBase", "tags": [ "Knowledge Bases" ], "description": "Restore a soft-deleted knowledge base. Agent assignments and connector links survive deletion, so the restored knowledge base is immediately live for previously-assigned agents. 404 if there is no soft-deleted knowledge base with that id in the org.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-bases/{id}/permanent": { "delete": { "operationId": "permanentlyDeleteKnowledgeBase", "tags": [ "Knowledge Bases" ], "description": "Permanently destroy a soft-deleted knowledge base (global admins only — a [`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete) or `knowledgeSource:admin` grant reaches the trash, not past it). Irreversible, with no grace period: the row and its agent and connector assignments are destroyed. Its connectors survive, detached. 404 if there is no soft-deleted knowledge base with that id in the org, which is also the answer when it is still live or the caller is not a global admin. Restore wins a race.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-bases/{id}/health": { "get": { "operationId": "getKnowledgeBaseHealth", "tags": [ "Knowledge Bases" ], "description": "Check the health of a knowledge base\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy" ] }, "message": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors": { "get": { "operationId": "getConnectors", "tags": [ "Connectors" ], "description": "List all connectors for the organization. `status=deleted` lists the soft-deleted ones instead — the trash view, which requires [`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete). Search and connector-type filtering behave identically on both slices; `knowledgeBaseId` is an active-only filter and is rejected with a 400 alongside `status=deleted`. The deleted slice carries identity only: `assignedAgents` comes back empty, since those links resolve to nothing while the connector is in the trash, and `totalDocsIngested` is not counted and comes back 0. It is also the one slice that never hides a row whose stored `config` no longer matches a known connector shape — the trash is the only place restore and permanent delete are offered.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "knowledgeBaseId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] }, "in": "query", "name": "connectorType", "required": false }, { "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. `deleted` lists soft-deleted connectors and requires [`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete)." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "maxItems": 250, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "ids", "required": false, "description": "Only these connectors (comma-separated IDs, at most 250), such as the ones a page shows or an agent uses. All of them come back in one page; `limit` and `offset` do not apply." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeAssignedAgents", "required": false, "description": "Attach each row's assigned agents (default true). False returns an empty `assignedAgents` array, meaning 'not requested'; `assignedAgentCount` is returned either way." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "org-wide", "team-scoped", "auto-sync-permissions" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "syncPermissionsFromSource": { "type": "boolean" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] }, "config": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "jira" ] }, "jiraBaseUrl": {}, "isCloud": { "type": "boolean" }, "projectKey": { "type": "string" }, "jqlQuery": { "type": "string" }, "commentEmailBlacklist": { "type": "array", "items": { "type": "string" } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "jiraBaseUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confluence" ] }, "confluenceUrl": {}, "isCloud": { "type": "boolean" }, "spaceKeys": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "cqlQuery": { "type": "string" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "confluenceUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "githubUrl": {}, "owner": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "pat", "github_app", "credential" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "githubAppConfigId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "" ] } ] }, "repos": { "type": "array", "items": { "type": "string" } }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "repositoryOverrides": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[^/\\\\\\s]+\\/[^/\\\\\\s]+$" }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repository" ], "additionalProperties": false } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "githubUrl", "owner" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "gitlabUrl": {}, "projectIds": { "type": "array", "items": { "type": "number" } }, "groupId": { "type": "string" }, "includeIssues": { "type": "boolean" }, "includeMergeRequests": { "type": "boolean" }, "includeMarkdownFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "gitlabUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "servicenow" ] }, "instanceUrl": {}, "includeIncidents": { "type": "boolean" }, "includeChanges": { "type": "boolean" }, "includeChangeRequests": { "type": "boolean" }, "includeProblems": { "type": "boolean" }, "includeBusinessApps": { "type": "boolean" }, "includeKnowledgeArticles": { "type": "boolean" }, "states": { "type": "array", "items": { "type": "string" } }, "assignmentGroups": { "type": "array", "items": { "type": "string" } }, "roleAudiences": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "batchSize": { "type": "number" }, "syncDataForLastMonths": { "type": "number", "minimum": 1, "maximum": 12 } }, "required": [ "type", "instanceUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notion" ] }, "databaseIds": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sharepoint" ] }, "tenantId": { "type": "string", "minLength": 1 }, "siteUrl": {}, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "includePages": { "type": "boolean" }, "pagePublicationStatus": { "description": "Site pages to sync by current publication status. Omitted means both for compatibility.", "type": "string", "enum": [ "published", "draft", "both" ] }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "siteUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gdrive" ] }, "authMode": { "type": "string", "enum": [ "service_account", "service_account_delegated", "oauth" ] }, "delegatedAdminEmail": { "type": "string" }, "connectedAccountEmail": { "type": "string" }, "driveId": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dropbox" ] }, "rootPath": { "type": "string" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "onedrive" ] }, "tenantId": { "type": "string", "minLength": 1 }, "userIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "userIds" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana" ] }, "workspaceGid": { "type": "string", "minLength": 1 }, "projectGids": { "type": "array", "items": { "type": "string" } }, "tagsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "workspaceGid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linear" ] }, "linearApiUrl": { "default": "https://api.linear.app" }, "teamIds": { "type": "array", "items": { "type": "string" } }, "projectIds": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "includeComments": { "type": "boolean" }, "includeProjects": { "type": "boolean" }, "includeCycles": { "type": "boolean" }, "batchSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "type", "linearApiUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "outline" ] }, "outlineUrl": {}, "collectionIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "outlineUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "salesforce" ] }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "soap_legacy" ] }, "clientId": { "type": "string", "minLength": 1 }, "loginUrl": { "default": "https://login.salesforce.com" }, "objects": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "advancedObjectConfigJson": { "type": "string" } }, "required": [ "type", "loginUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_crawler" ] }, "startUrl": {}, "renderJavaScript": { "type": "boolean" }, "renderWaitMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "additionalStartUrls": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowedOrigins": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "includePathPrefixes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "excludePathPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "contentSelector": { "type": "string", "minLength": 1, "maxLength": 500 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "requestDelayMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "userAgent": { "type": "string", "minLength": 1 }, "allowPrivateNetwork": { "type": "boolean" } }, "required": [ "type", "startUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perforce" ] }, "serverUrl": {}, "depotPaths": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string", "pattern": "^\\.?[A-Za-z0-9_-]+$" } }, "p4Port": { "type": "string", "pattern": "^(ssl:)?[A-Za-z0-9_.[\\]-]+:\\d{1,5}$" }, "adminUsername": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "serverUrl", "depotPaths" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mfiles" ] }, "baseUrl": {}, "vaultGuid": { "type": "string", "pattern": "^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$" }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "mfiles_password_token" ] }, "oauthTokenEndpoint": {}, "oauthScope": { "type": "string", "minLength": 1 }, "oauthResource": { "type": "string", "minLength": 1 }, "oauthAuthConfig": { "type": "string", "minLength": 1 }, "oauthAuthConfigScope": { "type": "string", "minLength": 1 }, "oauthAccountName": { "type": "string", "minLength": 1 }, "oauthUseIdToken": { "type": "boolean" }, "oauthClientAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "domain": { "type": "string" }, "objectTypeIds": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 500 }, "permissionExtensionMethod": { "type": "string", "minLength": 1 } }, "required": [ "type", "baseUrl", "vaultGuid" ], "additionalProperties": false } ] }, { "type": "object", "additionalProperties": {} } ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "schedule": { "type": "string" }, "ftsLanguage": { "$ref": "#/components/schemas/TextSearchLanguage" }, "permissionSyncIntervalSeconds": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "lastSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "lastSyncError": { "nullable": true, "type": "string" }, "lastPermissionSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastPermissionSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "checkpoint": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "aclConfigEpoch": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "assignedAgentCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalDocsIngested": { "type": "number" } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "syncPermissionsFromSource", "connectorType", "config", "secretId", "environmentId", "schedule", "ftsLanguage", "permissionSyncIntervalSeconds", "enabled", "lastSyncAt", "lastSyncStatus", "lastSyncError", "lastPermissionSyncAt", "lastPermissionSyncStatus", "checkpoint", "aclConfigEpoch", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels", "assignedAgents", "assignedAgentCount", "totalDocsIngested" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "post": { "operationId": "createConnector", "tags": [ "Connectors" ], "description": "Create a new connector\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:create`](/docs/reference/permissions#knowledgeSource:create): Create Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "nullable": true, "type": "string" }, "syncPermissionsFromSource": { "description": "Mirror each document's access control from the source, so a query only returns what the caller could open there. Needs an enterprise license and a connector type that supports it.", "type": "boolean" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] } ] }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "jira" ] }, "jiraBaseUrl": { "type": "string" }, "isCloud": { "type": "boolean" }, "projectKey": { "type": "string" }, "jqlQuery": { "type": "string" }, "commentEmailBlacklist": { "type": "array", "items": { "type": "string" } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "jiraBaseUrl", "isCloud" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confluence" ] }, "confluenceUrl": { "type": "string" }, "isCloud": { "type": "boolean" }, "spaceKeys": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "cqlQuery": { "type": "string" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "confluenceUrl", "isCloud" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "githubUrl": { "type": "string" }, "owner": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "pat", "github_app", "credential" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "githubAppConfigId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "" ] } ] }, "repos": { "type": "array", "items": { "type": "string" } }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "repositoryOverrides": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[^/\\\\\\s]+\\/[^/\\\\\\s]+$" }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repository" ] } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "githubUrl", "owner" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "gitlabUrl": { "type": "string" }, "projectIds": { "type": "array", "items": { "type": "number" } }, "groupId": { "type": "string" }, "includeIssues": { "type": "boolean" }, "includeMergeRequests": { "type": "boolean" }, "includeMarkdownFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "gitlabUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "servicenow" ] }, "instanceUrl": { "type": "string" }, "includeIncidents": { "type": "boolean" }, "includeChanges": { "type": "boolean" }, "includeChangeRequests": { "type": "boolean" }, "includeProblems": { "type": "boolean" }, "includeBusinessApps": { "type": "boolean" }, "includeKnowledgeArticles": { "type": "boolean" }, "states": { "type": "array", "items": { "type": "string" } }, "assignmentGroups": { "type": "array", "items": { "type": "string" } }, "roleAudiences": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "batchSize": { "type": "number" }, "syncDataForLastMonths": { "type": "number", "minimum": 1, "maximum": 12 } }, "required": [ "type", "instanceUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notion" ] }, "databaseIds": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sharepoint" ] }, "tenantId": { "type": "string", "minLength": 1 }, "siteUrl": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "includePages": { "type": "boolean" }, "pagePublicationStatus": { "description": "Site pages to sync by current publication status. Omitted means both for compatibility.", "type": "string", "enum": [ "published", "draft", "both" ] }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "siteUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gdrive" ] }, "authMode": { "type": "string", "enum": [ "service_account", "service_account_delegated", "oauth" ] }, "delegatedAdminEmail": { "type": "string" }, "connectedAccountEmail": { "type": "string" }, "driveId": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dropbox" ] }, "rootPath": { "type": "string" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "onedrive" ] }, "tenantId": { "type": "string", "minLength": 1 }, "userIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "userIds" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana" ] }, "workspaceGid": { "type": "string", "minLength": 1 }, "projectGids": { "type": "array", "items": { "type": "string" } }, "tagsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "workspaceGid" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linear" ] }, "linearApiUrl": { "type": "string" }, "teamIds": { "type": "array", "items": { "type": "string" } }, "projectIds": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "includeComments": { "type": "boolean" }, "includeProjects": { "type": "boolean" }, "includeCycles": { "type": "boolean" }, "batchSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "outline" ] }, "outlineUrl": { "type": "string" }, "collectionIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "outlineUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "salesforce" ] }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "soap_legacy" ] }, "clientId": { "type": "string", "minLength": 1 }, "loginUrl": { "type": "string" }, "objects": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "advancedObjectConfigJson": { "type": "string" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_crawler" ] }, "startUrl": { "type": "string" }, "renderJavaScript": { "type": "boolean" }, "renderWaitMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "additionalStartUrls": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowedOrigins": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "includePathPrefixes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "excludePathPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "contentSelector": { "type": "string", "minLength": 1, "maxLength": 500 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "requestDelayMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "userAgent": { "type": "string", "minLength": 1 }, "allowPrivateNetwork": { "type": "boolean" } }, "required": [ "type", "startUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perforce" ] }, "serverUrl": { "type": "string" }, "depotPaths": { "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "excludePaths": { "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "fileTypes": { "type": "array", "items": { "type": "string", "pattern": "^\\.?[A-Za-z0-9_-]+$" } }, "p4Port": { "type": "string", "pattern": "^(ssl:)?[A-Za-z0-9_.[\\]-]+:\\d{1,5}$" }, "adminUsername": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "serverUrl", "depotPaths" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mfiles" ] }, "baseUrl": { "type": "string" }, "vaultGuid": { "type": "string", "pattern": "^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$" }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "mfiles_password_token" ] }, "oauthTokenEndpoint": { "type": "string" }, "oauthScope": { "type": "string", "minLength": 1 }, "oauthResource": { "type": "string", "minLength": 1 }, "oauthAuthConfig": { "type": "string", "minLength": 1 }, "oauthAuthConfigScope": { "type": "string", "minLength": 1 }, "oauthAccountName": { "type": "string", "minLength": 1 }, "oauthUseIdToken": { "type": "boolean" }, "oauthClientAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "domain": { "type": "string" }, "objectTypeIds": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 500 }, "permissionExtensionMethod": { "type": "string", "minLength": 1 } }, "required": [ "type", "baseUrl", "vaultGuid" ] } ] }, "credentials": { "type": "object", "properties": { "email": { "type": "string" }, "apiToken": { "type": "string" }, "adminApiKey": { "type": "string" }, "githubApp": { "type": "object", "properties": { "githubUrl": { "type": "string" }, "appId": { "type": "string" }, "installationId": { "type": "string" } }, "required": [ "githubUrl", "appId", "installationId" ] }, "googleOAuth": { "type": "object", "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "refreshToken": { "type": "string" } }, "required": [ "clientId", "clientSecret" ] } }, "required": [ "apiToken" ] }, "schedule": { "type": "string" }, "ftsLanguage": { "allOf": [ { "$ref": "#/components/schemas/TextSearchLanguageInput" } ] }, "permissionSyncIntervalSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" }, "knowledgeBaseIds": { "type": "array", "items": { "type": "string" } }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name", "connectorType", "config" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "org-wide", "team-scoped", "auto-sync-permissions" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "syncPermissionsFromSource": { "type": "boolean" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "jira" ] }, "jiraBaseUrl": {}, "isCloud": { "type": "boolean" }, "projectKey": { "type": "string" }, "jqlQuery": { "type": "string" }, "commentEmailBlacklist": { "type": "array", "items": { "type": "string" } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "jiraBaseUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confluence" ] }, "confluenceUrl": {}, "isCloud": { "type": "boolean" }, "spaceKeys": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "cqlQuery": { "type": "string" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "confluenceUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "githubUrl": {}, "owner": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "pat", "github_app", "credential" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "githubAppConfigId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "" ] } ] }, "repos": { "type": "array", "items": { "type": "string" } }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "repositoryOverrides": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[^/\\\\\\s]+\\/[^/\\\\\\s]+$" }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repository" ], "additionalProperties": false } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "githubUrl", "owner" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "gitlabUrl": {}, "projectIds": { "type": "array", "items": { "type": "number" } }, "groupId": { "type": "string" }, "includeIssues": { "type": "boolean" }, "includeMergeRequests": { "type": "boolean" }, "includeMarkdownFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "gitlabUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "servicenow" ] }, "instanceUrl": {}, "includeIncidents": { "type": "boolean" }, "includeChanges": { "type": "boolean" }, "includeChangeRequests": { "type": "boolean" }, "includeProblems": { "type": "boolean" }, "includeBusinessApps": { "type": "boolean" }, "includeKnowledgeArticles": { "type": "boolean" }, "states": { "type": "array", "items": { "type": "string" } }, "assignmentGroups": { "type": "array", "items": { "type": "string" } }, "roleAudiences": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "batchSize": { "type": "number" }, "syncDataForLastMonths": { "type": "number", "minimum": 1, "maximum": 12 } }, "required": [ "type", "instanceUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notion" ] }, "databaseIds": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sharepoint" ] }, "tenantId": { "type": "string", "minLength": 1 }, "siteUrl": {}, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "includePages": { "type": "boolean" }, "pagePublicationStatus": { "description": "Site pages to sync by current publication status. Omitted means both for compatibility.", "type": "string", "enum": [ "published", "draft", "both" ] }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "siteUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gdrive" ] }, "authMode": { "type": "string", "enum": [ "service_account", "service_account_delegated", "oauth" ] }, "delegatedAdminEmail": { "type": "string" }, "connectedAccountEmail": { "type": "string" }, "driveId": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dropbox" ] }, "rootPath": { "type": "string" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "onedrive" ] }, "tenantId": { "type": "string", "minLength": 1 }, "userIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "userIds" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana" ] }, "workspaceGid": { "type": "string", "minLength": 1 }, "projectGids": { "type": "array", "items": { "type": "string" } }, "tagsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "workspaceGid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linear" ] }, "linearApiUrl": { "default": "https://api.linear.app" }, "teamIds": { "type": "array", "items": { "type": "string" } }, "projectIds": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "includeComments": { "type": "boolean" }, "includeProjects": { "type": "boolean" }, "includeCycles": { "type": "boolean" }, "batchSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "type", "linearApiUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "outline" ] }, "outlineUrl": {}, "collectionIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "outlineUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "salesforce" ] }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "soap_legacy" ] }, "clientId": { "type": "string", "minLength": 1 }, "loginUrl": { "default": "https://login.salesforce.com" }, "objects": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "advancedObjectConfigJson": { "type": "string" } }, "required": [ "type", "loginUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_crawler" ] }, "startUrl": {}, "renderJavaScript": { "type": "boolean" }, "renderWaitMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "additionalStartUrls": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowedOrigins": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "includePathPrefixes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "excludePathPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "contentSelector": { "type": "string", "minLength": 1, "maxLength": 500 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "requestDelayMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "userAgent": { "type": "string", "minLength": 1 }, "allowPrivateNetwork": { "type": "boolean" } }, "required": [ "type", "startUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perforce" ] }, "serverUrl": {}, "depotPaths": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string", "pattern": "^\\.?[A-Za-z0-9_-]+$" } }, "p4Port": { "type": "string", "pattern": "^(ssl:)?[A-Za-z0-9_.[\\]-]+:\\d{1,5}$" }, "adminUsername": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "serverUrl", "depotPaths" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mfiles" ] }, "baseUrl": {}, "vaultGuid": { "type": "string", "pattern": "^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$" }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "mfiles_password_token" ] }, "oauthTokenEndpoint": {}, "oauthScope": { "type": "string", "minLength": 1 }, "oauthResource": { "type": "string", "minLength": 1 }, "oauthAuthConfig": { "type": "string", "minLength": 1 }, "oauthAuthConfigScope": { "type": "string", "minLength": 1 }, "oauthAccountName": { "type": "string", "minLength": 1 }, "oauthUseIdToken": { "type": "boolean" }, "oauthClientAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "domain": { "type": "string" }, "objectTypeIds": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 500 }, "permissionExtensionMethod": { "type": "string", "minLength": 1 } }, "required": [ "type", "baseUrl", "vaultGuid" ], "additionalProperties": false } ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "schedule": { "type": "string" }, "ftsLanguage": { "$ref": "#/components/schemas/TextSearchLanguage" }, "permissionSyncIntervalSeconds": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "lastSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "lastSyncError": { "nullable": true, "type": "string" }, "lastPermissionSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastPermissionSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "checkpoint": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "aclConfigEpoch": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "syncPermissionsFromSource", "connectorType", "config", "secretId", "environmentId", "schedule", "ftsLanguage", "permissionSyncIntervalSeconds", "enabled", "lastSyncAt", "lastSyncStatus", "lastSyncError", "lastPermissionSyncAt", "lastPermissionSyncStatus", "checkpoint", "aclConfigEpoch", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:create" ] } } }, "/api/connectors/{id}": { "get": { "operationId": "getConnector", "tags": [ "Connectors" ], "description": "Get a connector by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "org-wide", "team-scoped", "auto-sync-permissions" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "syncPermissionsFromSource": { "type": "boolean" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] }, "config": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "jira" ] }, "jiraBaseUrl": {}, "isCloud": { "type": "boolean" }, "projectKey": { "type": "string" }, "jqlQuery": { "type": "string" }, "commentEmailBlacklist": { "type": "array", "items": { "type": "string" } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "jiraBaseUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confluence" ] }, "confluenceUrl": {}, "isCloud": { "type": "boolean" }, "spaceKeys": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "cqlQuery": { "type": "string" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "confluenceUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "githubUrl": {}, "owner": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "pat", "github_app", "credential" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "githubAppConfigId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "" ] } ] }, "repos": { "type": "array", "items": { "type": "string" } }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "repositoryOverrides": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[^/\\\\\\s]+\\/[^/\\\\\\s]+$" }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repository" ], "additionalProperties": false } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "githubUrl", "owner" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "gitlabUrl": {}, "projectIds": { "type": "array", "items": { "type": "number" } }, "groupId": { "type": "string" }, "includeIssues": { "type": "boolean" }, "includeMergeRequests": { "type": "boolean" }, "includeMarkdownFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "gitlabUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "servicenow" ] }, "instanceUrl": {}, "includeIncidents": { "type": "boolean" }, "includeChanges": { "type": "boolean" }, "includeChangeRequests": { "type": "boolean" }, "includeProblems": { "type": "boolean" }, "includeBusinessApps": { "type": "boolean" }, "includeKnowledgeArticles": { "type": "boolean" }, "states": { "type": "array", "items": { "type": "string" } }, "assignmentGroups": { "type": "array", "items": { "type": "string" } }, "roleAudiences": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "batchSize": { "type": "number" }, "syncDataForLastMonths": { "type": "number", "minimum": 1, "maximum": 12 } }, "required": [ "type", "instanceUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notion" ] }, "databaseIds": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sharepoint" ] }, "tenantId": { "type": "string", "minLength": 1 }, "siteUrl": {}, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "includePages": { "type": "boolean" }, "pagePublicationStatus": { "description": "Site pages to sync by current publication status. Omitted means both for compatibility.", "type": "string", "enum": [ "published", "draft", "both" ] }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "siteUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gdrive" ] }, "authMode": { "type": "string", "enum": [ "service_account", "service_account_delegated", "oauth" ] }, "delegatedAdminEmail": { "type": "string" }, "connectedAccountEmail": { "type": "string" }, "driveId": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dropbox" ] }, "rootPath": { "type": "string" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "onedrive" ] }, "tenantId": { "type": "string", "minLength": 1 }, "userIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "userIds" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana" ] }, "workspaceGid": { "type": "string", "minLength": 1 }, "projectGids": { "type": "array", "items": { "type": "string" } }, "tagsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "workspaceGid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linear" ] }, "linearApiUrl": { "default": "https://api.linear.app" }, "teamIds": { "type": "array", "items": { "type": "string" } }, "projectIds": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "includeComments": { "type": "boolean" }, "includeProjects": { "type": "boolean" }, "includeCycles": { "type": "boolean" }, "batchSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "type", "linearApiUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "outline" ] }, "outlineUrl": {}, "collectionIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "outlineUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "salesforce" ] }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "soap_legacy" ] }, "clientId": { "type": "string", "minLength": 1 }, "loginUrl": { "default": "https://login.salesforce.com" }, "objects": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "advancedObjectConfigJson": { "type": "string" } }, "required": [ "type", "loginUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_crawler" ] }, "startUrl": {}, "renderJavaScript": { "type": "boolean" }, "renderWaitMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "additionalStartUrls": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowedOrigins": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "includePathPrefixes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "excludePathPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "contentSelector": { "type": "string", "minLength": 1, "maxLength": 500 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "requestDelayMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "userAgent": { "type": "string", "minLength": 1 }, "allowPrivateNetwork": { "type": "boolean" } }, "required": [ "type", "startUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perforce" ] }, "serverUrl": {}, "depotPaths": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string", "pattern": "^\\.?[A-Za-z0-9_-]+$" } }, "p4Port": { "type": "string", "pattern": "^(ssl:)?[A-Za-z0-9_.[\\]-]+:\\d{1,5}$" }, "adminUsername": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "serverUrl", "depotPaths" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mfiles" ] }, "baseUrl": {}, "vaultGuid": { "type": "string", "pattern": "^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$" }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "mfiles_password_token" ] }, "oauthTokenEndpoint": {}, "oauthScope": { "type": "string", "minLength": 1 }, "oauthResource": { "type": "string", "minLength": 1 }, "oauthAuthConfig": { "type": "string", "minLength": 1 }, "oauthAuthConfigScope": { "type": "string", "minLength": 1 }, "oauthAccountName": { "type": "string", "minLength": 1 }, "oauthUseIdToken": { "type": "boolean" }, "oauthClientAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "domain": { "type": "string" }, "objectTypeIds": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 500 }, "permissionExtensionMethod": { "type": "string", "minLength": 1 } }, "required": [ "type", "baseUrl", "vaultGuid" ], "additionalProperties": false } ] }, { "type": "object", "additionalProperties": {} } ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "schedule": { "type": "string" }, "ftsLanguage": { "$ref": "#/components/schemas/TextSearchLanguage" }, "permissionSyncIntervalSeconds": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "lastSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "lastSyncError": { "nullable": true, "type": "string" }, "lastPermissionSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastPermissionSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "checkpoint": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "aclConfigEpoch": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "totalDocsIngested": { "type": "number" } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "syncPermissionsFromSource", "connectorType", "config", "secretId", "environmentId", "schedule", "ftsLanguage", "permissionSyncIntervalSeconds", "enabled", "lastSyncAt", "lastSyncStatus", "lastSyncError", "lastPermissionSyncAt", "lastPermissionSyncStatus", "checkpoint", "aclConfigEpoch", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels", "totalDocsIngested" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "put": { "operationId": "updateConnector", "tags": [ "Connectors" ], "description": "Update a connector\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "org-wide", "team-scoped", "auto-sync-permissions" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "jira" ] }, "jiraBaseUrl": { "type": "string" }, "isCloud": { "type": "boolean" }, "projectKey": { "type": "string" }, "jqlQuery": { "type": "string" }, "commentEmailBlacklist": { "type": "array", "items": { "type": "string" } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "jiraBaseUrl", "isCloud" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confluence" ] }, "confluenceUrl": { "type": "string" }, "isCloud": { "type": "boolean" }, "spaceKeys": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "cqlQuery": { "type": "string" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "confluenceUrl", "isCloud" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "githubUrl": { "type": "string" }, "owner": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "pat", "github_app", "credential" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "githubAppConfigId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "" ] } ] }, "repos": { "type": "array", "items": { "type": "string" } }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "repositoryOverrides": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[^/\\\\\\s]+\\/[^/\\\\\\s]+$" }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repository" ] } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "githubUrl", "owner" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "gitlabUrl": { "type": "string" }, "projectIds": { "type": "array", "items": { "type": "number" } }, "groupId": { "type": "string" }, "includeIssues": { "type": "boolean" }, "includeMergeRequests": { "type": "boolean" }, "includeMarkdownFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "gitlabUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "servicenow" ] }, "instanceUrl": { "type": "string" }, "includeIncidents": { "type": "boolean" }, "includeChanges": { "type": "boolean" }, "includeChangeRequests": { "type": "boolean" }, "includeProblems": { "type": "boolean" }, "includeBusinessApps": { "type": "boolean" }, "includeKnowledgeArticles": { "type": "boolean" }, "states": { "type": "array", "items": { "type": "string" } }, "assignmentGroups": { "type": "array", "items": { "type": "string" } }, "roleAudiences": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "batchSize": { "type": "number" }, "syncDataForLastMonths": { "type": "number", "minimum": 1, "maximum": 12 } }, "required": [ "type", "instanceUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notion" ] }, "databaseIds": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sharepoint" ] }, "tenantId": { "type": "string", "minLength": 1 }, "siteUrl": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "includePages": { "type": "boolean" }, "pagePublicationStatus": { "description": "Site pages to sync by current publication status. Omitted means both for compatibility.", "type": "string", "enum": [ "published", "draft", "both" ] }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "siteUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gdrive" ] }, "authMode": { "type": "string", "enum": [ "service_account", "service_account_delegated", "oauth" ] }, "delegatedAdminEmail": { "type": "string" }, "connectedAccountEmail": { "type": "string" }, "driveId": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dropbox" ] }, "rootPath": { "type": "string" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "onedrive" ] }, "tenantId": { "type": "string", "minLength": 1 }, "userIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "userIds" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana" ] }, "workspaceGid": { "type": "string", "minLength": 1 }, "projectGids": { "type": "array", "items": { "type": "string" } }, "tagsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "workspaceGid" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linear" ] }, "linearApiUrl": { "type": "string" }, "teamIds": { "type": "array", "items": { "type": "string" } }, "projectIds": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "includeComments": { "type": "boolean" }, "includeProjects": { "type": "boolean" }, "includeCycles": { "type": "boolean" }, "batchSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "outline" ] }, "outlineUrl": { "type": "string" }, "collectionIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "outlineUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "salesforce" ] }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "soap_legacy" ] }, "clientId": { "type": "string", "minLength": 1 }, "loginUrl": { "type": "string" }, "objects": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "advancedObjectConfigJson": { "type": "string" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_crawler" ] }, "startUrl": { "type": "string" }, "renderJavaScript": { "type": "boolean" }, "renderWaitMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "additionalStartUrls": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowedOrigins": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "includePathPrefixes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "excludePathPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "contentSelector": { "type": "string", "minLength": 1, "maxLength": 500 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "requestDelayMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "userAgent": { "type": "string", "minLength": 1 }, "allowPrivateNetwork": { "type": "boolean" } }, "required": [ "type", "startUrl" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perforce" ] }, "serverUrl": { "type": "string" }, "depotPaths": { "minItems": 1, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "excludePaths": { "type": "array", "items": { "type": "string", "maxLength": 1024 } }, "fileTypes": { "type": "array", "items": { "type": "string", "pattern": "^\\.?[A-Za-z0-9_-]+$" } }, "p4Port": { "type": "string", "pattern": "^(ssl:)?[A-Za-z0-9_.[\\]-]+:\\d{1,5}$" }, "adminUsername": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "serverUrl", "depotPaths" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mfiles" ] }, "baseUrl": { "type": "string" }, "vaultGuid": { "type": "string", "pattern": "^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$" }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "mfiles_password_token" ] }, "oauthTokenEndpoint": { "type": "string" }, "oauthScope": { "type": "string", "minLength": 1 }, "oauthResource": { "type": "string", "minLength": 1 }, "oauthAuthConfig": { "type": "string", "minLength": 1 }, "oauthAuthConfigScope": { "type": "string", "minLength": 1 }, "oauthAccountName": { "type": "string", "minLength": 1 }, "oauthUseIdToken": { "type": "boolean" }, "oauthClientAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "domain": { "type": "string" }, "objectTypeIds": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 500 }, "permissionExtensionMethod": { "type": "string", "minLength": 1 } }, "required": [ "type", "baseUrl", "vaultGuid" ] } ] }, "credentials": { "type": "object", "properties": { "email": { "type": "string" }, "apiToken": { "type": "string" }, "adminApiKey": { "type": "string" }, "githubApp": { "type": "object", "properties": { "githubUrl": { "type": "string" }, "appId": { "type": "string" }, "installationId": { "type": "string" } }, "required": [ "githubUrl", "appId", "installationId" ] }, "googleOAuth": { "type": "object", "properties": { "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "refreshToken": { "type": "string" } }, "required": [ "clientId", "clientSecret" ] } } }, "schedule": { "type": "string" }, "ftsLanguage": { "allOf": [ { "$ref": "#/components/schemas/TextSearchLanguageInput" } ] }, "permissionSyncIntervalSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "org-wide", "team-scoped", "auto-sync-permissions" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "syncPermissionsFromSource": { "type": "boolean" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "jira" ] }, "jiraBaseUrl": {}, "isCloud": { "type": "boolean" }, "projectKey": { "type": "string" }, "jqlQuery": { "type": "string" }, "commentEmailBlacklist": { "type": "array", "items": { "type": "string" } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "jiraBaseUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confluence" ] }, "confluenceUrl": {}, "isCloud": { "type": "boolean" }, "spaceKeys": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "cqlQuery": { "type": "string" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "confluenceUrl", "isCloud" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "githubUrl": {}, "owner": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "pat", "github_app", "credential" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 128 }, "githubAppConfigId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "" ] } ] }, "repos": { "type": "array", "items": { "type": "string" } }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "repositoryOverrides": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "string", "pattern": "^[^/\\\\\\s]+\\/[^/\\\\\\s]+$" }, "includeIssues": { "type": "boolean" }, "includePullRequests": { "type": "boolean" }, "includeRepositoryFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": [ "repository" ], "additionalProperties": false } }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "githubUrl", "owner" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "gitlabUrl": {}, "projectIds": { "type": "array", "items": { "type": "number" } }, "groupId": { "type": "string" }, "includeIssues": { "type": "boolean" }, "includeMergeRequests": { "type": "boolean" }, "includeMarkdownFiles": { "type": "boolean" }, "labelsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "gitlabUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "servicenow" ] }, "instanceUrl": {}, "includeIncidents": { "type": "boolean" }, "includeChanges": { "type": "boolean" }, "includeChangeRequests": { "type": "boolean" }, "includeProblems": { "type": "boolean" }, "includeBusinessApps": { "type": "boolean" }, "includeKnowledgeArticles": { "type": "boolean" }, "states": { "type": "array", "items": { "type": "string" } }, "assignmentGroups": { "type": "array", "items": { "type": "string" } }, "roleAudiences": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "batchSize": { "type": "number" }, "syncDataForLastMonths": { "type": "number", "minimum": 1, "maximum": 12 } }, "required": [ "type", "instanceUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notion" ] }, "databaseIds": { "type": "array", "items": { "type": "string" } }, "pageIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sharepoint" ] }, "tenantId": { "type": "string", "minLength": 1 }, "siteUrl": {}, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderPath": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "includePages": { "type": "boolean" }, "pagePublicationStatus": { "description": "Site pages to sync by current publication status. Omitted means both for compatibility.", "type": "string", "enum": [ "published", "draft", "both" ] }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "siteUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gdrive" ] }, "authMode": { "type": "string", "enum": [ "service_account", "service_account_delegated", "oauth" ] }, "delegatedAdminEmail": { "type": "string" }, "connectedAccountEmail": { "type": "string" }, "driveId": { "type": "string" }, "driveIds": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dropbox" ] }, "rootPath": { "type": "string" }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "number" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "onedrive" ] }, "tenantId": { "type": "string", "minLength": 1 }, "userIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folderId": { "type": "string" }, "recursive": { "type": "boolean" }, "maxDepth": { "type": "integer", "minimum": 1, "maximum": 100 }, "fileTypes": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "tenantId", "userIds" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asana" ] }, "workspaceGid": { "type": "string", "minLength": 1 }, "projectGids": { "type": "array", "items": { "type": "string" } }, "tagsToSkip": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "workspaceGid" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "linear" ] }, "linearApiUrl": { "default": "https://api.linear.app" }, "teamIds": { "type": "array", "items": { "type": "string" } }, "projectIds": { "type": "array", "items": { "type": "string" } }, "states": { "type": "array", "items": { "type": "string" } }, "includeComments": { "type": "boolean" }, "includeProjects": { "type": "boolean" }, "includeCycles": { "type": "boolean" }, "batchSize": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "type", "linearApiUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "outline" ] }, "outlineUrl": {}, "collectionIds": { "type": "array", "items": { "type": "string" } }, "batchSize": { "type": "number" } }, "required": [ "type", "outlineUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "salesforce" ] }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "soap_legacy" ] }, "clientId": { "type": "string", "minLength": 1 }, "loginUrl": { "default": "https://login.salesforce.com" }, "objects": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "advancedObjectConfigJson": { "type": "string" } }, "required": [ "type", "loginUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "web_crawler" ] }, "startUrl": {}, "renderJavaScript": { "type": "boolean" }, "renderWaitMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "additionalStartUrls": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowedOrigins": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "includePathPrefixes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "excludePathPatterns": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "contentSelector": { "type": "string", "minLength": 1, "maxLength": 500 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDepth": { "type": "integer", "minimum": 0, "maximum": 50 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "requestDelayMs": { "type": "integer", "minimum": 0, "maximum": 10000 }, "userAgent": { "type": "string", "minLength": 1 }, "allowPrivateNetwork": { "type": "boolean" } }, "required": [ "type", "startUrl" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "perforce" ] }, "serverUrl": {}, "depotPaths": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } }, "fileTypes": { "type": "array", "items": { "type": "string", "pattern": "^\\.?[A-Za-z0-9_-]+$" } }, "p4Port": { "type": "string", "pattern": "^(ssl:)?[A-Za-z0-9_.[\\]-]+:\\d{1,5}$" }, "adminUsername": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "type", "serverUrl", "depotPaths" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mfiles" ] }, "baseUrl": {}, "vaultGuid": { "type": "string", "pattern": "^\\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\}$" }, "authMethod": { "type": "string", "enum": [ "oauth_client_credentials", "mfiles_password_token" ] }, "oauthTokenEndpoint": {}, "oauthScope": { "type": "string", "minLength": 1 }, "oauthResource": { "type": "string", "minLength": 1 }, "oauthAuthConfig": { "type": "string", "minLength": 1 }, "oauthAuthConfigScope": { "type": "string", "minLength": 1 }, "oauthAccountName": { "type": "string", "minLength": 1 }, "oauthUseIdToken": { "type": "boolean" }, "oauthClientAuthMethod": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic" ] }, "domain": { "type": "string" }, "objectTypeIds": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 500 }, "permissionExtensionMethod": { "type": "string", "minLength": 1 } }, "required": [ "type", "baseUrl", "vaultGuid" ], "additionalProperties": false } ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "schedule": { "type": "string" }, "ftsLanguage": { "$ref": "#/components/schemas/TextSearchLanguage" }, "permissionSyncIntervalSeconds": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "lastSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "lastSyncError": { "nullable": true, "type": "string" }, "lastPermissionSyncAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastPermissionSyncStatus": { "nullable": true, "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "checkpoint": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "aclConfigEpoch": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "syncPermissionsFromSource", "connectorType", "config", "secretId", "environmentId", "schedule", "ftsLanguage", "permissionSyncIntervalSeconds", "enabled", "lastSyncAt", "lastSyncStatus", "lastSyncError", "lastPermissionSyncAt", "lastPermissionSyncStatus", "checkpoint", "aclConfigEpoch", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } }, "delete": { "operationId": "deleteConnector", "tags": [ "Connectors" ], "description": "Delete a connector\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/connectors/{id}/documents": { "get": { "operationId": "getConnectorDocuments", "tags": [ "Connectors" ], "description": "List documents for a connector\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "Only documents whose effective audience grants this upstream group (auto-sync-permissions connectors)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "sourceId": { "nullable": true, "type": "string" }, "connectorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "contentHash": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "acl": { "type": "array", "items": { "type": "string", "pattern": "^(org:\\*|team:.+|user_email:.+|oauth_client:.+|group:.+|container:.+)$" } }, "metadata": { "nullable": true, "type": "object", "additionalProperties": {} }, "embeddingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "chunkCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] } }, "required": [ "id", "organizationId", "sourceId", "connectorId", "title", "contentHash", "sourceUrl", "acl", "metadata", "embeddingStatus", "chunkCount", "createdAt", "updatedAt", "connectorType" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/documents/{docId}": { "get": { "operationId": "getConnectorDocument", "tags": [ "Connectors" ], "description": "Get a single connector document\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "docId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "sourceId": { "nullable": true, "type": "string" }, "connectorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "content": { "type": "string" }, "contentHash": { "type": "string" }, "sourceUrl": { "nullable": true, "type": "string" }, "acl": { "type": "array", "items": { "type": "string", "pattern": "^(org:\\*|team:.+|user_email:.+|oauth_client:.+|group:.+|container:.+)$" } }, "metadata": { "nullable": true, "type": "object", "additionalProperties": {} }, "embeddingStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "chunkCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "connectorType": { "anyOf": [ { "type": "string", "enum": [ "jira" ] }, { "type": "string", "enum": [ "confluence" ] }, { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "gitlab" ] }, { "type": "string", "enum": [ "servicenow" ] }, { "type": "string", "enum": [ "notion" ] }, { "type": "string", "enum": [ "sharepoint" ] }, { "type": "string", "enum": [ "gdrive" ] }, { "type": "string", "enum": [ "dropbox" ] }, { "type": "string", "enum": [ "onedrive" ] }, { "type": "string", "enum": [ "asana" ] }, { "type": "string", "enum": [ "linear" ] }, { "type": "string", "enum": [ "outline" ] }, { "type": "string", "enum": [ "salesforce" ] }, { "type": "string", "enum": [ "web_crawler" ] }, { "type": "string", "enum": [ "perforce" ] }, { "type": "string", "enum": [ "mfiles" ] }, { "type": "string", "enum": [ "file_upload" ] } ] } }, "required": [ "id", "organizationId", "sourceId", "connectorId", "title", "content", "contentHash", "sourceUrl", "acl", "metadata", "embeddingStatus", "chunkCount", "createdAt", "updatedAt", "connectorType" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "delete": { "operationId": "deleteConnectorDocument", "tags": [ "Connectors" ], "description": "Delete a connector document\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "docId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/connectors/{id}/documents/bulk": { "delete": { "operationId": "bulkDeleteConnectorDocuments", "tags": [ "Connectors" ], "description": "Delete several of a connector's synced documents in one request. Ids belonging to a different connector — or to no document at all — are reported in `failed` as not found and leave the rest of the batch applied. Deleting a synced document removes it until the next sync brings it back; to stop it returning, remove it at the source or narrow the connector's scope.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] }, { "type": "object", "properties": { "all": { "type": "boolean", "enum": [ true ], "description": "Delete everything matching the filters below rather than an id list." }, "search": { "description": "Same title search the listing applies.", "type": "string" }, "group": { "description": "Same group filter the listing applies.", "type": "string" } }, "required": [ "all" ], "description": "Filter mode. A connector's corpus routinely runs to tens of thousands of documents, which is neither a sane request body as uuids nor worth authorizing row by row — so the filter travels instead and the database does the work in one statement. The response carries `affected` rather than a per-row list." } ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/connectors/bulk": { "patch": { "operationId": "bulkUpdateConnectors", "tags": [ "Connectors" ], "description": "Change who can see several connectors in one request. Every connector in the batch moves to the same audience, and the ACL refresh each one needs runs per connector exactly as the single update runs it. `auto-sync-permissions` is deliberately not accepted here: switching a connector to it fail-closes its whole corpus until a permission pass completes, and it is gated on the connector's own type, so it stays a per-connector decision.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." }, "visibility": { "type": "string", "enum": [ "org-wide", "team-scoped" ], "description": "The audience every connector in the batch moves to." }, "teamIds": { "description": "Only meaningful for `team-scoped`; required there.", "type": "array", "items": { "type": "string" } } }, "required": [ "ids", "visibility" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } }, "delete": { "operationId": "bulkDeleteConnectors", "tags": [ "Connectors" ], "description": "Soft-delete several connectors in one request. As with the single delete, each one's queued syncs are cancelled and its stored credential is destroyed — a restored connector comes back disabled and re-authenticates. A connector the caller may not delete is reported in `failed` while the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/connectors/{id}/restore": { "post": { "operationId": "restoreConnector", "tags": [ "Connectors" ], "description": "Restore a soft-deleted connector. The stored credential was destroyed when the connector was deleted, so it is restored DISABLED — re-authenticate, then re-enable it to resume syncing. 404 if there is no soft-deleted connector with that id in the org that the caller may manage — restoring one is gated on the same visibility as editing or deleting it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/connectors/{id}/permanent": { "delete": { "operationId": "permanentlyDeleteConnector", "tags": [ "Connectors" ], "description": "Permanently destroy a soft-deleted connector (global admins only — a [`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete) or `knowledgeSource:admin` grant reaches the trash, not past it). Irreversible, with no grace period: its synced documents and their chunks, run history, access mappings, and assignments are all destroyed. 404 if there is no soft-deleted connector with that id in the org, which is also the answer when it is still live or the caller is not a global admin. Restore wins a race.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/connectors/{id}/sync": { "post": { "operationId": "syncConnector", "tags": [ "Connectors" ], "description": "Manually trigger a connector sync\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "taskId", "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/permission-sync": { "post": { "operationId": "triggerPermissionSync", "tags": [ "Connectors" ], "description": "Manually trigger a permission-sync pass for an auto-sync-permissions connector\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "taskId", "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/permission-coverage": { "get": { "operationId": "getPermissionSyncCoverage", "tags": [ "Connectors" ], "description": "Live ACL coverage for an auto-sync-permissions connector: how many ingested documents are tagged vs still fail-closed (awaiting a permission-sync pass)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalDocuments": { "type": "number" }, "failClosedDocuments": { "type": "number" }, "permissionSyncRunning": { "type": "boolean" }, "nextScheduledAt": { "nullable": true, "type": "string" } }, "required": [ "totalDocuments", "failClosedDocuments", "permissionSyncRunning", "nextScheduledAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/user-groups": { "get": { "operationId": "getConnectorUserGroups", "tags": [ "Connectors" ], "description": "Synced external user groups for an auto-sync-permissions connector: each group's member emails, the Archestra org users they resolve to, and how many documents grant the group\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "truncated": { "type": "boolean" }, "totalMemberships": { "type": "number" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "token": { "type": "string" }, "documentCount": { "type": "number" }, "lastSyncedAt": { "nullable": true, "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "accountType": { "nullable": true, "type": "string" }, "user": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "resolvedVia": { "nullable": true, "type": "string", "enum": [ "override", "email" ] } }, "required": [ "accountId", "displayName", "email", "accountType", "user", "resolvedVia" ], "additionalProperties": false } } }, "required": [ "groupId", "name", "token", "documentCount", "lastSyncedAt", "members" ], "additionalProperties": false } } }, "required": [ "truncated", "totalMemberships", "groups" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/member-overrides": { "put": { "operationId": "upsertConnectorMemberOverride", "tags": [ "Connectors" ], "description": "Manually map an upstream member account to an Archestra user for an auto-sync-permissions connector — the admin escape hatch when the upstream hides the member's email from every credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalAccountId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "externalAccountId", "userId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/member-overrides/{externalAccountId}": { "delete": { "operationId": "deleteConnectorMemberOverride", "tags": [ "Connectors" ], "description": "Remove a manual member mapping; the member falls back to email-based resolution (fail-closed when the upstream hides their email)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalAccountId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/force-resync": { "post": { "operationId": "forceResyncConnector", "tags": [ "Connectors" ], "description": "Force a full re-sync: deletes all documents, chunks, run history, and resets the checkpoint\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "taskId", "status" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/test": { "post": { "operationId": "testConnectorConnection", "tags": [ "Connectors" ], "description": "Test a connector connection\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/gdrive/oauth/start": { "post": { "operationId": "startGoogleDriveConnectorOAuth", "tags": [ "Connectors" ], "description": "Begin the Google authorization-code flow for a Google Drive connector in individual mode. Returns the URL to send the browser to; the connector being authorized travels in a signed state parameter, because Google matches the redirect URI exactly.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnTo": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorizationUrl": { "type": "string" } }, "required": [ "authorizationUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/gdrive/oauth/callback": { "get": { "operationId": "completeGoogleDriveConnectorOAuth", "tags": [ "Connectors" ], "description": "Where Google returns the browser after an individual Google Drive authorization. Requires the session of the person who started the flow: the signed state proves only that this deployment issued a flow, so on its own it would let one person's authorization be redeemed onto another person's connector.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "code", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "error", "required": false } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/knowledge-bases": { "post": { "operationId": "assignConnectorToKnowledgeBases", "tags": [ "Connectors" ], "description": "Assign a connector to one or more knowledge bases\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseIds": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "knowledgeBaseIds" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } }, "get": { "operationId": "getConnectorKnowledgeBases", "tags": [ "Connectors" ], "description": "List knowledge bases assigned to a connector\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "org-wide", "team-scoped" ] }, "teamIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "name", "description", "visibility", "teamIds", "status", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/knowledge-bases/{kbId}": { "delete": { "operationId": "unassignConnectorFromKnowledgeBase", "tags": [ "Connectors" ], "description": "Unassign a connector from a knowledge base\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "kbId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/connectors/{id}/runs": { "get": { "operationId": "getConnectorRuns", "tags": [ "Connectors" ], "description": "List connector runs\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "content", "permission" ] }, "in": "query", "name": "runType", "required": false }, { "schema": { "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "changes", "no-changes" ] }, "in": "query", "name": "result", "required": false, "description": "Only runs that changed something (or nothing)" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "runType": { "type": "string", "enum": [ "content", "permission" ] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "documentsProcessed": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "documentsIngested": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalItems": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalBatches": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completedBatches": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "itemErrors": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "itemsSkipped": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "documentsWithoutText": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "error": { "nullable": true, "type": "string" }, "checkpoint": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "stats": { "nullable": true, "type": "object", "properties": { "mode": { "type": "string", "enum": [ "full", "delta" ] }, "totalDocs": { "type": "number" }, "docsScanned": { "type": "number" }, "aclsChanged": { "type": "number" }, "chunksRewritten": { "type": "number" }, "failClosed": { "type": "number" }, "groupsSynced": { "type": "number" }, "membershipsUpserted": { "type": "number" }, "membershipsRemoved": { "type": "number" }, "containersSynced": { "type": "number" }, "containersChanged": { "type": "number" }, "containerAudienceFailures": { "type": "number" }, "docsAdopted": { "type": "number" }, "docsReassigned": { "type": "number" }, "groupSyncFailed": { "type": "boolean" }, "contentSyncActiveDuringRun": { "type": "boolean" } }, "required": [ "totalDocs", "docsScanned", "aclsChanged", "chunksRewritten", "failClosed", "groupsSynced", "membershipsUpserted", "contentSyncActiveDuringRun" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "connectorId", "status", "runType", "startedAt", "completedAt", "documentsProcessed", "documentsIngested", "totalItems", "totalBatches", "completedBatches", "itemErrors", "itemsSkipped", "documentsWithoutText", "error", "checkpoint", "stats", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "queued": { "type": "object", "properties": { "content": { "type": "boolean" }, "permission": { "type": "boolean" } }, "required": [ "content", "permission" ], "additionalProperties": false } }, "required": [ "data", "pagination", "queued" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/runs/{runId}": { "get": { "operationId": "getConnectorRun", "tags": [ "Connectors" ], "description": "Get a single connector run (including logs)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "queued", "running", "success", "completed_with_errors", "no_documents", "failed", "partial", "cancelled", "superseded" ] }, "runType": { "type": "string", "enum": [ "content", "permission" ] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "documentsProcessed": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "documentsIngested": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalItems": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalBatches": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completedBatches": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "itemErrors": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "itemsSkipped": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "documentsWithoutText": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "error": { "nullable": true, "type": "string" }, "logs": { "nullable": true, "type": "string" }, "checkpoint": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "stats": { "nullable": true, "type": "object", "properties": { "mode": { "type": "string", "enum": [ "full", "delta" ] }, "totalDocs": { "type": "number" }, "docsScanned": { "type": "number" }, "aclsChanged": { "type": "number" }, "chunksRewritten": { "type": "number" }, "failClosed": { "type": "number" }, "groupsSynced": { "type": "number" }, "membershipsUpserted": { "type": "number" }, "membershipsRemoved": { "type": "number" }, "containersSynced": { "type": "number" }, "containersChanged": { "type": "number" }, "containerAudienceFailures": { "type": "number" }, "docsAdopted": { "type": "number" }, "docsReassigned": { "type": "number" }, "groupSyncFailed": { "type": "boolean" }, "contentSyncActiveDuringRun": { "type": "boolean" } }, "required": [ "totalDocs", "docsScanned", "aclsChanged", "chunksRewritten", "failClosed", "groupsSynced", "membershipsUpserted", "contentSyncActiveDuringRun" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "connectorId", "status", "runType", "startedAt", "completedAt", "documentsProcessed", "documentsIngested", "totalItems", "totalBatches", "completedBatches", "itemErrors", "itemsSkipped", "documentsWithoutText", "error", "logs", "checkpoint", "stats", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/connectors/{id}/runs/{runId}/cancel": { "post": { "operationId": "cancelConnectorRun", "tags": [ "Connectors" ], "description": "Cancel an in-progress document sync. Documents already ingested remain available; the worker stops before writing its next source batch.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "type": "boolean", "enum": [ true ] } }, "required": [ "cancelled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/knowledge-files/labels/keys": { "get": { "operationId": "knowledgeFileLabelKeys", "tags": [ "Knowledge Files" ], "description": "Get all label keys used by knowledge files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-files/labels/values": { "get": { "operationId": "knowledgeFileLabelValues", "tags": [ "Knowledge Files" ], "description": "Get all label values used by knowledge files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-files": { "get": { "operationId": "getKnowledgeFiles", "tags": [ "Knowledge Files" ], "description": "List documents in the knowledge file repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "directoryId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "directoryId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "visibility": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "contentHash": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "teamIds": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "directoryId", "visibility", "filename", "mimeType", "sizeBytes", "contentHash", "createdByServiceAccountId", "createdAt", "createdBy", "knowledgeBases", "teamIds", "labels" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "post": { "operationId": "uploadKnowledgeFile", "tags": [ "Knowledge Files" ], "description": "Upload a document into the knowledge file repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:create`](/docs/reference/permissions#knowledgeSource:create): Create Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 512 }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1 }, "directoryId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "filename", "mimeType", "content" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "directoryId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "visibility": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "contentHash": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "teamIds": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "directoryId", "visibility", "filename", "mimeType", "sizeBytes", "contentHash", "createdByServiceAccountId", "createdAt", "createdBy", "knowledgeBases", "teamIds", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:create" ] } } }, "/api/knowledge-files/{fileId}/content": { "put": { "operationId": "upsertKnowledgeFile", "tags": [ "Knowledge Files" ], "description": "Create or replace a document using a stable client-generated UUID and index it into a knowledge base. Only the uploader may replace it. Existing audiences and labels are preserved. Re-indexes all knowledge bases already linked to the file; the caller must have access to each.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:create`](/docs/reference/permissions#knowledgeSource:create): Create Knowledge Bases and Connectors\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 512 }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1, "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$", "description": "Base64-encoded file bytes" }, "knowledgeBaseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "filename", "mimeType", "content", "knowledgeBaseId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "results": { "type": "array", "items": { "type": "object", "properties": { "knowledgeBaseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "indexed": { "type": "number" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "fileId", "error" ], "additionalProperties": false } } }, "required": [ "knowledgeBaseId", "indexed", "failures" ], "additionalProperties": false } } }, "required": [ "id", "results" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:create", "knowledgeSource:update" ] } }, "get": { "operationId": "getKnowledgeFileContent", "tags": [ "Knowledge Files" ], "description": "Stream the bytes of a repository document. Safe types render inline (PDF, images, plain text); everything else downloads.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } } }, "/api/knowledge-files/from-attachment": { "post": { "operationId": "promoteAttachmentToKnowledgeFile", "tags": [ "Knowledge Files" ], "description": "Copy a file attached to a chat into the knowledge file repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:create`](/docs/reference/permissions#knowledgeSource:create): Create Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "filename": { "type": "string", "minLength": 1, "maxLength": 512 }, "directoryId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "knowledgeBaseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "attachmentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "directoryId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "visibility": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "contentHash": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "teamIds": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "directoryId", "visibility", "filename", "mimeType", "sizeBytes", "contentHash", "createdByServiceAccountId", "createdAt", "createdBy", "knowledgeBases", "teamIds", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:create" ] } } }, "/api/knowledge-files/{fileId}": { "patch": { "operationId": "updateKnowledgeFile", "tags": [ "Knowledge Files" ], "description": "Rename a document, move it, or change its labels. Who can read it is its permission grants; the retired `visibility` and `teamIds` fields are refused.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 512 }, "directoryId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "directoryId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "visibility": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "contentHash": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "knowledgeBases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "teamIds": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "directoryId", "visibility", "filename", "mimeType", "sizeBytes", "contentHash", "createdByServiceAccountId", "createdAt", "createdBy", "knowledgeBases", "teamIds", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } }, "delete": { "operationId": "deleteKnowledgeFile", "tags": [ "Knowledge Files" ], "description": "Delete a repository document and every document indexed from it\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-files/bulk": { "delete": { "operationId": "bulkDeleteKnowledgeFiles", "tags": [ "Knowledge Files" ], "description": "Delete several repository documents in one request, along with every document indexed from each. Ids the caller cannot see are reported in `failed` and leave the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-files/index": { "post": { "operationId": "indexKnowledgeFiles", "tags": [ "Knowledge Files" ], "description": "Index repository documents into a knowledge base, creating it when a name is given\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileIds": { "default": [], "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "directoryIds": { "default": [], "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "knowledgeBaseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "newKnowledgeBaseName": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseId": { "type": "string" }, "indexed": { "type": "number" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "fileId", "error" ], "additionalProperties": false } } }, "required": [ "knowledgeBaseId", "indexed", "failures" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } } }, "/api/knowledge-directories": { "get": { "operationId": "getKnowledgeDirectories", "tags": [ "Knowledge Files" ], "description": "List knowledge file directories\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:read`](/docs/reference/permissions#knowledgeSource:read): View Knowledge Bases and Connectors", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "visibility": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamIds": { "type": "array", "items": { "type": "string" } }, "fileCount": { "type": "number" } }, "required": [ "id", "organizationId", "name", "visibility", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy", "teamIds", "fileCount" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:read" ] } }, "post": { "operationId": "createKnowledgeDirectory", "tags": [ "Knowledge Files" ], "description": "Create a knowledge file directory. A directory only organizes documents; the retired `visibility` and `teamIds` fields are refused.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:create`](/docs/reference/permissions#knowledgeSource:create): Create Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "visibility": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamIds": { "type": "array", "items": { "type": "string" } }, "fileCount": { "type": "number" } }, "required": [ "id", "organizationId", "name", "visibility", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy", "teamIds", "fileCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:create" ] } } }, "/api/knowledge-directories/{directoryId}": { "patch": { "operationId": "updateKnowledgeDirectory", "tags": [ "Knowledge Files" ], "description": "Rename a directory. The retired `visibility` and `teamIds` fields are refused.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:update`](/docs/reference/permissions#knowledgeSource:update): Modify Knowledge Bases and Connectors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "directoryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "visibility": { "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamIds": { "type": "array", "items": { "type": "string" } }, "fileCount": { "type": "number" } }, "required": [ "id", "organizationId", "name", "visibility", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy", "teamIds", "fileCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:update" ] } }, "delete": { "operationId": "deleteKnowledgeDirectory", "tags": [ "Knowledge Files" ], "description": "Delete a directory; its files move to the repository root\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "directoryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/knowledge-directories/bulk": { "delete": { "operationId": "bulkDeleteKnowledgeDirectories", "tags": [ "Knowledge Files" ], "description": "Delete several directories in one request. As with the single delete, the files inside each move to the repository root rather than being destroyed. Ids that match no directory are reported in `failed` and leave the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`knowledgeSource:delete`](/docs/reference/permissions#knowledgeSource:delete): Delete Knowledge Bases and Connectors, view the deleted ones, and restore them", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "knowledgeSource:delete" ] } } }, "/api/limits/labels/keys": { "get": { "operationId": "limitLabelKeys", "tags": [ "Limits" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:read`, or a session-authenticated team admin. Label suggestions include only visible limits.", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:read`](/docs/reference/permissions#llmLimit:read), or a session-authenticated team admin. Label suggestions include only visible limits." } }, "/api/limits/labels/values": { "get": { "operationId": "limitLabelValues", "tags": [ "Limits" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:read`, or a session-authenticated team admin. Label suggestions include only visible limits.", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:read`](/docs/reference/permissions#llmLimit:read), or a session-authenticated team admin. Label suggestions include only visible limits." } }, "/api/limits": { "get": { "operationId": "getLimits", "tags": [ "Limits" ], "description": "Get all limits with optional filtering and per-model usage breakdown\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:read`](/docs/reference/permissions#llmLimit:read) for organization-wide access. A session-authenticated team admin receives only limits for teams they directly administer, with optional entity filters.", "parameters": [ { "schema": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "in": "query", "name": "entityType", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "entityId", "required": false }, { "schema": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "in": "query", "name": "limitType", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "entityType": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "entityId": { "type": "string" }, "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string" }, "teamManaged": { "type": "boolean", "description": "Whether a team admin created this team limit. Team admins can change or delete only these." }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "lastCleanup": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "throughputUsage": { "type": "object", "properties": { "currentUsage": { "type": "number", "description": "Recorded usage. Token limits count only provider-reported tokens; requests already in flight can exceed the cap." }, "resetsAt": { "type": "string", "description": "Minute: projected full allowance recovery without new traffic. Other intervals: next reset." } }, "required": [ "currentUsage", "resetsAt" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "estimatedUsage": { "description": "Spend limits only: part of the spend is estimated because a model had no price for some of the tokens a request used.", "type": "boolean" }, "modelUsage": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "tokensIn": { "type": "number" }, "tokensOut": { "type": "number" }, "cost": { "type": "number" } }, "required": [ "model", "tokensIn", "tokensOut", "cost" ], "additionalProperties": false } } }, "required": [ "id", "entityType", "entityId", "limitType", "limitValue", "behavior", "mcpServerName", "toolName", "teamManaged", "lastCleanup", "createdAt", "updatedAt", "labels" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:read` for organization-wide access. A session-authenticated team admin receives only limits for teams they directly administer, with optional entity filters.", "permissions": [] } }, "post": { "operationId": "createLimit", "tags": [ "Limits" ], "description": "Create a new limit\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:create`](/docs/reference/permissions#llmLimit:create), or a session-authenticated team admin creating a limit on their own team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "entityId": { "type": "string" }, "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string", "maxLength": 500 }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "lastCleanup": { "nullable": true }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } }, "required": [ "entityType", "entityId", "limitType", "limitValue" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "entityType": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "entityId": { "type": "string" }, "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string" }, "teamManaged": { "type": "boolean", "description": "Whether a team admin created this team limit. Team admins can change or delete only these." }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "lastCleanup": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityType", "entityId", "limitType", "limitValue", "behavior", "mcpServerName", "toolName", "teamManaged", "lastCleanup", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:create`, or a session-authenticated team admin creating a limit on their own team.", "permissions": [] } } }, "/api/limits/{id}": { "get": { "operationId": "getLimit", "tags": [ "Limits" ], "description": "Get a limit by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:read`](/docs/reference/permissions#llmLimit:read), or a session-authenticated team admin for a limit on their own team.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "entityType": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "entityId": { "type": "string" }, "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string" }, "teamManaged": { "type": "boolean", "description": "Whether a team admin created this team limit. Team admins can change or delete only these." }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "lastCleanup": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "throughputUsage": { "type": "object", "properties": { "currentUsage": { "type": "number", "description": "Recorded usage. Token limits count only provider-reported tokens; requests already in flight can exceed the cap." }, "resetsAt": { "type": "string", "description": "Minute: projected full allowance recovery without new traffic. Other intervals: next reset." } }, "required": [ "currentUsage", "resetsAt" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "estimatedUsage": { "description": "Spend limits only: part of the spend is estimated because a model had no price for some of the tokens a request used.", "type": "boolean" }, "modelUsage": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "tokensIn": { "type": "number" }, "tokensOut": { "type": "number" }, "cost": { "type": "number" } }, "required": [ "model", "tokensIn", "tokensOut", "cost" ], "additionalProperties": false } } }, "required": [ "id", "entityType", "entityId", "limitType", "limitValue", "behavior", "mcpServerName", "toolName", "teamManaged", "lastCleanup", "createdAt", "updatedAt", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:read`, or a session-authenticated team admin for a limit on their own team.", "permissions": [] } }, "patch": { "operationId": "updateLimit", "tags": [ "Limits" ], "description": "Update a limit\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:update`](/docs/reference/permissions#llmLimit:update), or a session-authenticated team admin updating a limit on their own team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string", "maxLength": 500 }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "lastCleanup": { "type": "string", "nullable": true, "enum": [ null ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "entityType": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "entityId": { "type": "string" }, "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string" }, "teamManaged": { "type": "boolean", "description": "Whether a team admin created this team limit. Team admins can change or delete only these." }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "lastCleanup": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityType", "entityId", "limitType", "limitValue", "behavior", "mcpServerName", "toolName", "teamManaged", "lastCleanup", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:update`, or a session-authenticated team admin updating a limit on their own team.", "permissions": [] } }, "delete": { "operationId": "deleteLimit", "tags": [ "Limits" ], "description": "Delete a limit\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:delete`](/docs/reference/permissions#llmLimit:delete), or a session-authenticated team admin deleting a limit on their own team.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:delete`, or a session-authenticated team admin deleting a limit on their own team.", "permissions": [] } } }, "/api/limits/{id}/reset": { "post": { "operationId": "resetLimitUsage", "tags": [ "Limits" ], "description": "Reset a spend limit's current window to $0, so the requests it blocks run again. Cost reports keep the past spend. A calendar interval keeps its schedule. A rolling interval next resets one interval from now.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:update`](/docs/reference/permissions#llmLimit:update), or a session-authenticated team admin resetting a limit on their own team.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "entityType": { "type": "string", "enum": [ "organization", "team", "agent", "user", "virtual_key", "environment", "llm_oauth_client" ] }, "entityId": { "type": "string" }, "limitType": { "type": "string", "enum": [ "token_cost", "requests", "tokens", "requests_per_minute", "tokens_per_minute", "mcp_server_calls", "tool_calls" ] }, "limitValue": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "behavior": { "type": "string", "enum": [ "hard", "soft" ] }, "mcpServerName": { "nullable": true, "type": "string", "maxLength": 255 }, "toolName": { "nullable": true, "type": "string", "maxLength": 255 }, "model": { "nullable": true, "type": "array", "items": { "type": "string" } }, "reason": { "nullable": true, "type": "string" }, "teamManaged": { "type": "boolean", "description": "Whether a team admin created this team limit. Team admins can change or delete only these." }, "cleanupInterval": { "type": "string", "enum": [ "minute", "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "lastCleanup": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityType", "entityId", "limitType", "limitValue", "behavior", "mcpServerName", "toolName", "teamManaged", "lastCleanup", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:update`, or a session-authenticated team admin resetting a limit on their own team.", "permissions": [] } } }, "/api/limits/bulk": { "delete": { "operationId": "bulkDeleteLimits", "tags": [ "Limits" ], "description": "Delete several limits in one request. Missing or out-of-organization ids are reported in `failed` while visible limits are deleted.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmLimit:delete`](/docs/reference/permissions#llmLimit:delete), or a session-authenticated team admin deleting only limits for teams they administer. Unauthorized targets are reported as not found.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Limit ids to delete. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmLimit:delete`, or a session-authenticated team admin deleting only limits for teams they administer. Unauthorized targets are reported as not found.", "permissions": [] } } }, "/api/llm-provider-models/labels/keys": { "get": { "operationId": "llmProviderModelLabelKeys", "tags": [ "LLM Models" ], "description": "Get all label keys used by models\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:read`](/docs/reference/permissions#llmModel:read): View synced LLM models and capabilities", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:read" ] } } }, "/api/llm-provider-models/labels/values": { "get": { "operationId": "llmProviderModelLabelValues", "tags": [ "LLM Models" ], "description": "Get all label values used by models\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:read`](/docs/reference/permissions#llmModel:read): View synced LLM models and capabilities", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:read" ] } } }, "/api/llm-models/available": { "get": { "operationId": "getLlmModels", "tags": [ "LLM Models" ], "description": "Get available LLM models from configured provider API keys. Models are fetched from the provider-backed catalog and include capabilities when available.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "in": "query", "name": "provider", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "apiKeyId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "isEmbedding", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dbId": { "type": "string" }, "displayName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "createdAt": { "type": "string" }, "capabilities": { "type": "object", "properties": { "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "outputLength": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "supportedEndpoints": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses" ] } }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "recommendedForAgents": { "nullable": true, "type": "boolean" }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isCustomPrice": { "type": "boolean" }, "priceSource": { "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "cachePriceSource": { "nullable": true, "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "mediaPricing": { "nullable": true, "type": "object", "properties": { "per": { "type": "string", "enum": [ "million_tokens", "million_characters", "minute" ] }, "input": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } }, "output": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } } }, "required": [ "per", "input", "output" ], "additionalProperties": false } }, "required": [ "contextLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "outputLength", "supportedReasoningEfforts", "recommendedForAgents", "pricePerMillionInput", "pricePerMillionOutput", "isCustomPrice", "priceSource", "pricePerMillionCacheRead", "pricePerMillionCacheWrite", "cachePriceSource", "mediaPricing" ], "additionalProperties": false }, "isBest": { "type": "boolean" }, "isFree": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "requiresUserConnection": { "type": "boolean" }, "isConnected": { "type": "boolean" } }, "required": [ "id", "dbId", "displayName", "provider", "isFree" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/sync": { "post": { "operationId": "syncLlmModels", "tags": [ "LLM Models" ], "description": "Sync models from providers for all visible API keys and store them in the database\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:update`](/docs/reference/permissions#llmModel:update): Sync the model catalog and see every model, including ones not shared with you", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "apiKeyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "requiresReauthentication": { "type": "boolean" } }, "required": [ "apiKeyId", "name", "provider", "requiresReauthentication" ], "additionalProperties": false } } }, "required": [ "success", "failures" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:update" ] } } }, "/api/llm-models": { "get": { "operationId": "getModelsWithApiKeys", "tags": [ "LLM Models" ], "description": "Get all synced LLM models with their linked provider API keys.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "apiKeyIds", "required": false, "description": "Only models linked to one of these provider keys." }, { "schema": { "type": "boolean" }, "in": "query", "name": "embedding", "required": false, "description": "Only embedding models (models with known dimensions)." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeAssignments", "required": false, "description": "Include each model's teams, users and labels (default true). False returns them empty, for pickers that show only the models." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalId": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "outputLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "customContextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "customOutputLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "supportedEndpoints": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "promptPricePerToken": { "nullable": true, "type": "string" }, "completionPricePerToken": { "nullable": true, "type": "string" }, "cacheReadPricePerToken": { "nullable": true, "type": "string" }, "cacheWritePricePerToken": { "nullable": true, "type": "string" }, "customPricePerMillionInput": { "nullable": true, "type": "string" }, "customPricePerMillionOutput": { "nullable": true, "type": "string" }, "customPricePerMillionCacheRead": { "nullable": true, "type": "string" }, "customPricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "syncedLongContextPricing": { "nullable": true, "type": "object", "properties": { "threshold": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "pricePerMillionInput": { "type": "string" }, "pricePerMillionOutput": { "type": "string" }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" } }, "required": [ "threshold", "pricePerMillionInput", "pricePerMillionOutput", "pricePerMillionCacheRead", "pricePerMillionCacheWrite" ], "additionalProperties": false }, "longContextThreshold": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "longContextPricePerMillionInput": { "nullable": true, "type": "string" }, "longContextPricePerMillionOutput": { "nullable": true, "type": "string" }, "longContextPricePerMillionCacheRead": { "nullable": true, "type": "string" }, "longContextPricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "ignored": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "defaultParameters": { "nullable": true, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } }, "configuredParameters": { "nullable": true, "type": "object", "properties": { "temperature": { "type": "number", "minimum": 0 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "repeat_penalty": { "type": "number", "minimum": 0 }, "seed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stop": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 256 } }, "num_ctx": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "num_predict": { "type": "integer", "minimum": -2, "maximum": 9007199254740991 }, "reasoning_effort": { "type": "string", "enum": [ "none", "low", "medium", "high" ] } }, "additionalProperties": false }, "discoveredViaLlmProxy": { "type": "boolean" }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "isBest": { "type": "boolean" }, "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "provider": { "type": "string" }, "scope": { "type": "string" }, "isSystem": { "type": "boolean" } }, "required": [ "id", "name", "provider", "scope", "isSystem" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isCustomPrice": { "type": "boolean" }, "priceSource": { "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "cachePriceSource": { "nullable": true, "type": "string", "enum": [ "custom", "models_dev", "provider", "aws", "derived_multiplier", "default" ] }, "mediaPricing": { "nullable": true, "type": "object", "properties": { "per": { "type": "string", "enum": [ "million_tokens", "million_characters", "minute" ] }, "input": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } }, "output": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "text", "image", "audio", "text_and_image" ] }, "usd": { "type": "number" } }, "required": [ "kind", "usd" ], "additionalProperties": false } } }, "required": [ "per", "input", "output" ], "additionalProperties": false }, "isFree": { "type": "boolean" }, "effectiveContextLength": { "nullable": true, "type": "number" }, "embeddingClientImageCapable": { "nullable": true, "type": "boolean" } }, "required": [ "id", "externalId", "provider", "modelId", "description", "contextLength", "outputLength", "customContextLength", "customOutputLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "supportedEndpoints", "supportedReasoningEfforts", "promptPricePerToken", "completionPricePerToken", "cacheReadPricePerToken", "cacheWritePricePerToken", "customPricePerMillionInput", "customPricePerMillionOutput", "customPricePerMillionCacheRead", "customPricePerMillionCacheWrite", "syncedLongContextPricing", "longContextThreshold", "longContextPricePerMillionInput", "longContextPricePerMillionOutput", "longContextPricePerMillionCacheRead", "longContextPricePerMillionCacheWrite", "ignored", "embeddingDimensions", "defaultParameters", "configuredParameters", "discoveredViaLlmProxy", "lastSyncedAt", "createdAt", "updatedAt", "isBest", "apiKeys", "teams", "users", "labels", "pricePerMillionInput", "pricePerMillionOutput", "isCustomPrice", "priceSource", "pricePerMillionCacheRead", "pricePerMillionCacheWrite", "cachePriceSource", "mediaPricing", "isFree", "effectiveContextLength", "embeddingClientImageCapable" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/key-model-ids": { "get": { "operationId": "getLlmModelIdsByKey", "tags": [ "LLM Models" ], "description": "For each provider key the caller can see, the ids of the models it serves, leaving out hidden models. The models are the ones GET /api/llm-models lists for that key.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "apiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "apiKeyId", "modelIds" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/options": { "get": { "operationId": "getLlmModelOptions", "tags": [ "LLM Models" ], "description": "The models GET /api/llm-models lists, in the same order, with only what a model picker shows: name, provider and price.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "description": { "nullable": true, "type": "string" }, "pricePerMillionInput": { "nullable": true, "type": "string" }, "pricePerMillionOutput": { "nullable": true, "type": "string" }, "isFree": { "type": "boolean" }, "isBest": { "type": "boolean" } }, "required": [ "id", "modelId", "provider", "description", "pricePerMillionInput", "pricePerMillionOutput", "isFree", "isBest" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/bulk": { "patch": { "operationId": "bulkUpdateModels", "tags": [ "LLM Models" ], "description": "Update several LLM models in one request. Today the only bulk-editable field is `ignored`, which hides a model from pickers and blocks new executions, including direct provider requests, without deleting it. Ids that match no model are reported in `failed` and leave the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." }, "ignored": { "type": "boolean", "description": "Whether every model in the batch is hidden." } }, "required": [ "ids", "ignored" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/{id}": { "delete": { "operationId": "deleteModel", "tags": [ "LLM Models" ], "description": "Remove an unconfigured model entry observed in proxy requests. Saved pricing, provider links, sharing settings and retained references prevent removal. Recorded interactions and spend are retained. Another request may rediscover the model.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:update`](/docs/reference/permissions#llmModel:update): Sync the model catalog and see every model, including ones not shared with you", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:update" ] } }, "patch": { "operationId": "updateModel", "tags": [ "LLM Models" ], "description": "Update LLM model details including custom pricing and modalities.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customPricePerMillionInput": { "nullable": true, "type": "string" }, "customPricePerMillionOutput": { "nullable": true, "type": "string" }, "customPricePerMillionCacheRead": { "nullable": true, "type": "string" }, "customPricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "longContextThreshold": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10000000 }, "longContextPricePerMillionInput": { "nullable": true, "type": "string" }, "longContextPricePerMillionOutput": { "nullable": true, "type": "string" }, "longContextPricePerMillionCacheRead": { "nullable": true, "type": "string" }, "longContextPricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "customContextLength": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10000000 }, "customOutputLength": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10000000 }, "ignored": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensionsInput" } ] }, "inputModalities": { "nullable": true, "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "configuredParameters": { "nullable": true, "type": "object", "properties": { "temperature": { "type": "number", "minimum": 0 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "repeat_penalty": { "type": "number", "minimum": 0 }, "seed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stop": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 256 } }, "num_ctx": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "num_predict": { "type": "integer", "minimum": -2, "maximum": 9007199254740991 }, "reasoning_effort": { "type": "string", "enum": [ "none", "low", "medium", "high" ] } } }, "teamIds": { "not": {} }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "externalId": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "contextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "outputLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "customContextLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "customOutputLength": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "inputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "outputModalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supportsToolCalling": { "nullable": true, "type": "boolean" }, "supportsReasoningEffort": { "nullable": true, "type": "boolean" }, "supportedEndpoints": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "supportedReasoningEfforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "promptPricePerToken": { "nullable": true, "type": "string" }, "completionPricePerToken": { "nullable": true, "type": "string" }, "cacheReadPricePerToken": { "nullable": true, "type": "string" }, "cacheWritePricePerToken": { "nullable": true, "type": "string" }, "customPricePerMillionInput": { "nullable": true, "type": "string" }, "customPricePerMillionOutput": { "nullable": true, "type": "string" }, "customPricePerMillionCacheRead": { "nullable": true, "type": "string" }, "customPricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "syncedLongContextPricing": { "nullable": true, "type": "object", "properties": { "threshold": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "pricePerMillionInput": { "type": "string" }, "pricePerMillionOutput": { "type": "string" }, "pricePerMillionCacheRead": { "nullable": true, "type": "string" }, "pricePerMillionCacheWrite": { "nullable": true, "type": "string" } }, "required": [ "threshold", "pricePerMillionInput", "pricePerMillionOutput", "pricePerMillionCacheRead", "pricePerMillionCacheWrite" ], "additionalProperties": false }, "longContextThreshold": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "longContextPricePerMillionInput": { "nullable": true, "type": "string" }, "longContextPricePerMillionOutput": { "nullable": true, "type": "string" }, "longContextPricePerMillionCacheRead": { "nullable": true, "type": "string" }, "longContextPricePerMillionCacheWrite": { "nullable": true, "type": "string" }, "ignored": { "type": "boolean" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "defaultParameters": { "nullable": true, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } }, "configuredParameters": { "nullable": true, "type": "object", "properties": { "temperature": { "type": "number", "minimum": 0 }, "top_p": { "type": "number", "minimum": 0, "maximum": 1 }, "top_k": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "repeat_penalty": { "type": "number", "minimum": 0 }, "seed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stop": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 256 } }, "num_ctx": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "num_predict": { "type": "integer", "minimum": -2, "maximum": 9007199254740991 }, "reasoning_effort": { "type": "string", "enum": [ "none", "low", "medium", "high" ] } }, "additionalProperties": false }, "discoveredViaLlmProxy": { "type": "boolean" }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "provider", "modelId", "description", "contextLength", "outputLength", "customContextLength", "customOutputLength", "inputModalities", "outputModalities", "supportsToolCalling", "supportsReasoningEffort", "supportedEndpoints", "supportedReasoningEfforts", "promptPricePerToken", "completionPricePerToken", "cacheReadPricePerToken", "cacheWritePricePerToken", "customPricePerMillionInput", "customPricePerMillionOutput", "customPricePerMillionCacheRead", "customPricePerMillionCacheWrite", "syncedLongContextPricing", "longContextThreshold", "longContextPricePerMillionInput", "longContextPricePerMillionOutput", "longContextPricePerMillionCacheRead", "longContextPricePerMillionCacheWrite", "ignored", "embeddingDimensions", "defaultParameters", "configuredParameters", "discoveredViaLlmProxy", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/{id}/cost-backfill/preview": { "post": { "operationId": "previewModelCostBackfill", "tags": [ "LLM Models" ], "description": "Preview recomputing the recorded cost of a model's past requests: recorded and recomputed cost per day, and what a recompute from `since` would change. Pass `prices` to preview unsaved custom prices.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string", "maxLength": 64 }, "since": { "nullable": true }, "prices": { "type": "object", "properties": { "input": { "nullable": true, "type": "string" }, "output": { "nullable": true, "type": "string" }, "cacheRead": { "nullable": true, "type": "string" }, "cacheWrite": { "nullable": true, "type": "string" } }, "required": [ "input", "output", "cacheRead", "cacheWrite" ] } }, "required": [ "timeZone" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "availability": { "type": "string", "enum": [ "available", "index_pending", "provider_reported_cost", "needs_custom_price" ] }, "instancePriced": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recordedCost": { "type": "number" }, "recomputedCost": { "type": "number" } }, "required": [ "day", "requests", "recordedCost", "recomputedCost" ], "additionalProperties": false } }, "window": { "nullable": true, "type": "object", "properties": { "requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "subscriptionRequests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "users": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recordedCost": { "type": "number" }, "recomputedCost": { "type": "number" } }, "required": [ "requests", "subscriptionRequests", "users", "recordedCost", "recomputedCost" ], "additionalProperties": false } }, "required": [ "availability", "instancePriced", "days", "window" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-models/{id}/cost-backfill": { "post": { "operationId": "startModelCostBackfill", "tags": [ "LLM Models" ], "description": "Recompute the recorded cost of a model's past requests from `since` (all of them when null) at its current prices. Runs in the background; poll the GET endpoint for progress. It also re-prices each request's settled receipt and corrects the spend limits whose current window holds the charge.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "nullable": true }, "prices": { "description": "The custom prices you saved and expect the recompute to use. When the model's prices no longer match, nothing starts (409).", "type": "object", "properties": { "input": { "nullable": true, "type": "string" }, "output": { "nullable": true, "type": "string" }, "cacheRead": { "nullable": true, "type": "string" }, "cacheWrite": { "nullable": true, "type": "string" } }, "required": [ "input", "output", "cacheRead", "cacheWrite" ] } }, "required": [ "since" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "since": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "rowsEstimated": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "rowsScanned": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "rowsUpdated": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "error": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "modelId", "since", "cutoff", "status", "rowsEstimated", "rowsScanned", "rowsUpdated", "error", "createdAt", "completedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "get": { "operationId": "getModelCostBackfill", "tags": [ "LLM Models" ], "description": "The model's most recent cost recompute and its progress, or null when none was started.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "since": { "type": "string", "format": "date-time" }, "cutoff": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "rowsEstimated": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "rowsScanned": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "rowsUpdated": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "error": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "modelId", "since", "cutoff", "status", "rowsEstimated", "rowsScanned", "rowsUpdated", "error", "createdAt", "completedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-provider-api-keys/labels/keys": { "get": { "operationId": "llmProviderApiKeyLabelKeys", "tags": [ "LLM Provider API Keys" ], "description": "Get all label keys used by model provider API keys\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:read`](/docs/reference/permissions#llmProviderApiKey:read): Open LLM provider API keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:read" ] } } }, "/api/llm-provider-api-keys/labels/values": { "get": { "operationId": "llmProviderApiKeyLabelValues", "tags": [ "LLM Provider API Keys" ], "description": "Get all label values used by model provider API keys\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:read`](/docs/reference/permissions#llmProviderApiKey:read): Open LLM provider API keys", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:read" ] } } }, "/api/llm-provider-api-keys": { "get": { "operationId": "getLlmProviderApiKeys", "tags": [ "LLM Provider API Keys" ], "description": "Get all LLM provider API keys visible to the current user based on scope access\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "in": "query", "name": "provider", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createLlmProviderApiKey", "tags": [ "LLM Provider API Keys" ], "description": "Create a new LLM provider API key with specified visibility\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "apiKey": { "type": "string", "minLength": 1 }, "baseUrl": { "nullable": true, "type": "string", "format": "uri" }, "inferenceBaseUrl": { "nullable": true, "type": "string", "format": "uri" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "shared": { "default": false, "description": "Omitted or false: the key is yours alone (you own it and only you use it). True: a shared key with no owner, used by whoever its initialGrants reach. A service account cannot own a key, so it must send true.", "type": "boolean" }, "isPrimary": { "type": "boolean" }, "awsAccessKeyId": { "type": "string", "minLength": 1 }, "awsSecretAccessKey": { "type": "string", "minLength": 1 }, "awsSessionToken": { "type": "string", "minLength": 1 }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name", "provider" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-provider-api-keys/available": { "get": { "operationId": "getAvailableLlmProviderApiKeys", "tags": [ "LLM Provider API Keys" ], "description": "Get LLM provider API keys available for the current user to use\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:read`](/docs/reference/permissions#llmProviderApiKey:read): Open LLM provider API keys", "parameters": [ { "schema": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "in": "query", "name": "provider", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "includeKeyId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:read" ] } } }, "/api/llm-provider-api-keys/{id}": { "get": { "operationId": "getLlmProviderApiKey", "tags": [ "LLM Provider API Keys" ], "description": "Get a specific LLM provider API key\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateLlmProviderApiKey", "tags": [ "LLM Provider API Keys" ], "description": "Update an LLM provider API key (name, API key value, or runtime connection settings)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "apiKey": { "type": "string", "minLength": 1 }, "baseUrl": { "nullable": true, "type": "string", "format": "uri" }, "inferenceBaseUrl": { "nullable": true, "type": "string", "format": "uri" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isPrimary": { "type": "boolean" }, "awsAccessKeyId": { "type": "string", "minLength": 1 }, "awsSecretAccessKey": { "type": "string", "minLength": 1 }, "awsSessionToken": { "type": "string", "minLength": 1 }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteLlmProviderApiKey", "tags": [ "LLM Provider API Keys" ], "description": "Delete an LLM provider API key. Virtual API keys and OAuth clients that mapped only this key are deleted with it; those that also map other provider keys keep those. Knowledge base settings that used the key are cleared.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-provider-api-keys/{id}/reconnect": { "post": { "operationId": "reconnectLlmProviderApiKey", "tags": [ "LLM Provider API Keys" ], "description": "Re-authenticate the caller's own personal subscription key in place, rotating its stored credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1 } }, "required": [ "apiKey" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "userId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "baseUrl": { "nullable": true, "type": "string" }, "inferenceBaseUrl": { "nullable": true, "type": "string" }, "extraHeaders": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "isSystem": { "type": "boolean" }, "isPrimary": { "type": "boolean" }, "requiresReauthentication": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teamName": { "nullable": true, "type": "string" }, "userName": { "nullable": true, "type": "string" }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "bestModelId": { "nullable": true, "type": "string" }, "isAgentKey": { "type": "boolean" }, "subscriptionKind": { "nullable": true, "type": "string", "enum": [ "chatgpt", "github-copilot", "microsoft-365-copilot", "x-premium" ] }, "isGithubAppKey": { "type": "boolean" }, "githubOrganization": { "nullable": true, "type": "string" }, "githubOrganizationName": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "name", "provider", "secretId", "scope", "userId", "teamId", "baseUrl", "inferenceBaseUrl", "extraHeaders", "isSystem", "isPrimary", "createdByServiceAccountId", "createdAt", "updatedAt", "createdBy" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-provider-api-keys/bulk": { "delete": { "operationId": "bulkDeleteLlmProviderApiKeys", "tags": [ "LLM Provider API Keys" ], "description": "Delete several LLM provider API keys in one request. Keys outside the caller's organization and protected system keys are reported in `failed` while the remaining keys are deleted. Virtual API keys and OAuth clients that mapped only a deleted key are deleted with it; those that also map other provider keys keep those. Knowledge base settings that used a deleted key are cleared.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-proxy": { "get": { "operationId": "getLlmProxy", "tags": [ "LLM Proxy" ], "description": "Get the LLM Proxy\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:read`](/docs/reference/permissions#llmProxy:read): View the LLM Proxy and its connection details", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" } }, "required": [ "id", "identityProviderId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:read" ] } }, "patch": { "operationId": "updateLlmProxy", "tags": [ "LLM Proxy" ], "description": "Update the LLM Proxy configuration\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProxy:update`](/docs/reference/permissions#llmProxy:update): Modify LLM Proxy configuration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identityProviderId": { "nullable": true, "type": "string" } }, "required": [ "identityProviderId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "identityProviderId": { "nullable": true, "type": "string" } }, "required": [ "id", "identityProviderId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProxy:update" ] } } }, "/api/mcp/app/{appId}": { "post": { "operationId": "mcpAppProxyPost", "tags": [ "MCP App Runtime" ], "description": "Handle MCP App JSON-RPC requests for an app. The caller must have access to the app.\n\nAuthentication:\n\nUse a browser session or an Archestra API key. External MCP clients can send a personal token or an app-scoped OAuth access token as a Bearer token. Organization and team tokens cannot access an app because they have no viewer.\n\nAuthorization:\n\nThe caller must have `use` access to the app. Calls to assigned tools must be allowed for the app.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "dynamic", "note": "The caller must have `use` access to the app. Calls to assigned tools must be allowed for the app.", "permissions": [] } } }, "/v1/mcp/{profileId}": { "get": { "operationId": "mcpGatewayGet", "tags": [ "MCP Gateway" ], "description": "Open an MCP Gateway SSE stream for a client that requests one. Other GET requests return 405 because the gateway does not offer a standalone stream for them.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "profileId", "required": true } ], "responses": { "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "405": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "error": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "id": { "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_rate_limit_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_service_unavailable_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "operationId": "mcpGatewayPost", "tags": [ "MCP Gateway" ], "description": "Send an MCP JSON-RPC request through the gateway for the specified agent profile. Authenticate with a platform-managed bearer token or agent ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "profileId", "required": true } ], "responses": { "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_rate_limit_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_service_unavailable_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "default": { "description": "Default Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/mcp/{profileId}/messages": { "post": { "operationId": "mcpGatewaySseMessage", "tags": [ "MCP Gateway" ], "description": "Send a JSON-RPC message for a legacy HTTP+SSE session. The gateway sends the result on the SSE stream opened by GET, not in this response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "sessionId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "profileId", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_rate_limit_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_service_unavailable_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/mcp/{profileId}/runtime-status": { "post": { "operationId": "reportAgentRuntimeStatus", "tags": [ "MCP Gateway" ], "description": "Update the attention state of a native agent run using its MCP Gateway credential. This does not change the run's lifecycle state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "attentionState": { "anyOf": [ { "type": "string", "enum": [ "input_required", "auth_required" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] } }, "required": [ "taskId", "attentionState" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "profileId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "boolean" } }, "required": [ "updated" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_rate_limit_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_service_unavailable_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/mcp/{agentId}": { "post": { "operationId": "mcpProxyPost", "tags": [ "MCP App Runtime" ], "description": "Handle MCP App JSON-RPC requests through an agent's MCP Gateway. The caller must have access to the agent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nThe caller must have access to the agent. App tools must be visible to apps.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "dynamic", "note": "The caller must have access to the agent. App tools must be visible to apps.", "permissions": [] } } }, "/api/mcp/server/{mcpServerId}": { "post": { "operationId": "mcpServerProxyPost", "tags": [ "MCP App Runtime" ], "description": "Handle MCP App JSON-RPC requests for an installed MCP server. The caller must have access to the server.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nThe caller must have access to the installed MCP server. App tools must be visible to apps.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "mcpServerId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "dynamic", "note": "The caller must have access to the installed MCP server. App tools must be visible to apps.", "permissions": [] } } }, "/api/mcp_server/auto_mode_agents/page": { "get": { "operationId": "getMcpServerAutoModeAgentPage", "tags": [ "MCP Server" ], "description": "Count visible automatic agents or fetch a bounded cursor page, optionally excluding explicit assignments to a readable catalog.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "catalogId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "afterAgentId", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false }, { "schema": { "default": "false", "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "summary", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false }, "totalAutoCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationId": { "type": "string" } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } } }, "/api/mcp_server/auto_mode_agents": { "get": { "operationId": "getMcpServerAutoModeAgents", "tags": [ "MCP Server" ], "description": "Get the organization's auto-mode agents (implicit access to all tools). The set is org-wide — these agents can reach every MCP server — so it is served once here instead of being embedded on every server row.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } } }, "/api/mcp_server": { "get": { "operationId": "getMcpServers", "tags": [ "MCP Server" ], "description": "Get all installed MCP servers\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "catalogId", "required": false }, { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "catalogIds", "required": false, "description": "Only installs of these catalog items (comma-separated, at most 100)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "in": "query", "name": "catalogSlug", "required": false, "description": "Only installs of catalog items whose name, slugified as in tool names (lowercase, spaces as _, other characters dropped), is this." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeAssignedAgents", "required": false, "description": "Include each listed install's assigned agents. Defaults to false, which returns an empty `assignedAgents` for every install. The lookup covers every install in the response, so narrow the list with `catalogId` when you need only some. GET /api/mcp_server/{id} returns the agents of one install." }, { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "assignmentScope", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "assignmentTeamIds", "required": false }, { "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by lifecycle status. `deleted` lists soft-deleted (uninstalled) installs and requires delete permission and is limited to connections you can uninstall." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] }, "alertMutes": { "type": "array", "items": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } }, "canUseCredential": { "type": "boolean", "description": "Whether the caller may present this install's stored credential to the upstream — their own connection, or one shared with them. False for another member's personal connection, which the listing still returns to installation admins so they can manage it." } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt", "alertMutes", "canUseCredential" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } }, "post": { "operationId": "installMcpServer", "tags": [ "MCP Server" ], "description": "Install an MCP server (from catalog or custom)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "type": "object", "additionalProperties": { "type": "string" } }, "desktopArguments": { "nullable": true, "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "default": "personal", "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "userId": { "type": "string" }, "userConfigValues": { "type": "object", "additionalProperties": { "type": "string" } }, "agentIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "accessToken": { "type": "string" } }, "required": [ "name", "catalogId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/mcp_server/{id}": { "get": { "operationId": "getMcpServer", "tags": [ "MCP Server" ], "description": "Get MCP server by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } }, "delete": { "operationId": "deleteMcpServer", "tags": [ "MCP Server" ], "description": "Delete/uninstall an MCP server\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:delete`](/docs/reference/permissions#mcpServerInstallation:delete): Uninstall, view deleted, and restore MCP servers within your access", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:delete" ] } } }, "/api/mcp_server/{id}/reauthenticate": { "patch": { "operationId": "reauthenticateMcpServer", "tags": [ "MCP Server" ], "description": "Update MCP server secret after re-authentication (clears OAuth refresh errors)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "accessToken": { "type": "string" }, "userConfigValues": { "type": "object", "additionalProperties": { "type": "string" } }, "environmentValues": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/mcp_server/bulk": { "delete": { "operationId": "bulkDeleteMcpServers", "tags": [ "MCP Server" ], "description": "Uninstall several MCP servers in one request. Each id is authorized exactly as the single uninstall authorizes its own, so a built-in server, an app-backing server (owned by the Apps lifecycle), or one the caller may not revoke is reported in `failed` while the rest of the batch still applies. Uninstall is a recoverable soft delete: stored credentials are retained so a restore recovers them, and only the live Kubernetes Secret is torn down.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:delete`](/docs/reference/permissions#mcpServerInstallation:delete): Uninstall, view deleted, and restore MCP servers within your access", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:delete" ] } } }, "/api/mcp_server/{id}/restore": { "post": { "operationId": "restoreMcpServer", "tags": [ "MCP Server" ], "description": "Restore a soft-deleted (uninstalled) MCP server. Flag-only: the server is marked for manual reinstall, not re-provisioned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:delete`](/docs/reference/permissions#mcpServerInstallation:delete): Uninstall, view deleted, and restore MCP servers within your access", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:delete" ] } } }, "/api/mcp_server/{id}/desktop-arguments": { "put": { "operationId": "updateMcpServerDesktopArguments", "tags": [ "MCP Server" ], "description": "Set the arguments the signed-in user adds to the command of a desktop MCP server, for their own installation. The MCP bridge on their device starts the MCP server again with them.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "desktopArguments": { "nullable": true, "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 } } }, "required": [ "desktopArguments" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/mcp_server/{id}/alert-mutes/{kind}": { "put": { "operationId": "muteMcpServerAlert", "tags": [ "MCP Server" ], "description": "Dismiss one alert on an MCP connection for the calling user only. The fingerprint pins it to one failure episode; dismissing again replaces the previous decision.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issueFingerprint": { "type": "string", "minLength": 1, "maxLength": 500 }, "reason": { "default": "", "type": "string", "maxLength": 500 } }, "required": [ "issueFingerprint" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string" }, "mcpServerId": { "nullable": true, "type": "string" }, "issueKind": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "issueFingerprint": { "type": "string" }, "reason": { "type": "string" }, "mutedAt": { "type": "string", "format": "date-time" } }, "required": [ "catalogId", "mcpServerId", "issueKind", "issueFingerprint", "reason", "mutedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } }, "delete": { "operationId": "unmuteMcpServerAlert", "tags": [ "MCP Server" ], "description": "Restore one dismissed MCP connection alert to the calling user's view.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "in": "query", "name": "issueFingerprint", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "failed-to-start", "not-running", "needs-reauth" ] }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } } }, "/api/mcp_server/{id}/installation-status": { "get": { "operationId": "getMcpServerInstallationStatus", "tags": [ "MCP Server" ], "description": "Get the installation status of an MCP server (for polling during local server installation)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" } }, "required": [ "localInstallationStatus", "localInstallationError" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } } }, "/api/mcp_server/{id}/tools": { "get": { "operationId": "getMcpServerTools", "tags": [ "MCP Server" ], "description": "Get all tools for an MCP server\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "type": "object", "additionalProperties": {} }, "createdAt": { "type": "string", "format": "date-time" }, "group": { "nullable": true, "type": "string" }, "assignedAgentCount": { "type": "number" }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "parameters", "createdAt", "group", "assignedAgentCount", "assignedAgents" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } } }, "/api/mcp_server/{id}/inspect": { "post": { "operationId": "inspectMcpServer", "tags": [ "MCP Server" ], "description": "Inspect a running MCP server (list tools or call a tool)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:read`](/docs/reference/permissions#mcpServerInstallation:read): View installed MCP servers and their status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "tools/list", "tools/call" ] }, "toolName": { "type": "string" }, "toolArguments": { "type": "object", "additionalProperties": {} } }, "required": [ "method" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:read" ] } } }, "/api/mcp_server/{id}/reinstall": { "post": { "operationId": "reinstallMcpServer", "tags": [ "MCP Server" ], "description": "Reinstall an MCP server without losing tool assignments\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environmentValues": { "type": "object", "additionalProperties": { "type": "string" } }, "userConfigValues": { "type": "object", "additionalProperties": { "type": "string" } }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "deploymentName": { "nullable": true, "type": "string" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverType": { "type": "string", "enum": [ "local", "remote", "builtin", "app", "desktop_mcp" ] }, "secretId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "environmentValues": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "desktopArguments": { "nullable": true, "type": "array", "items": { "type": "string" } }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerId": { "nullable": true, "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "reinstallRequired": { "type": "boolean" }, "reinstallReason": { "nullable": true, "type": "string", "enum": [ "new-input", "restart" ] }, "localInstallationStatus": { "type": "string", "enum": [ "idle", "pending", "discovering-tools", "success", "error" ] }, "localInstallationError": { "nullable": true, "type": "string" }, "oauthRefreshError": { "nullable": true, "type": "string", "enum": [ "refresh_failed", "no_refresh_token" ] }, "oauthRefreshErrorMessage": { "nullable": true, "type": "string" }, "oauthRefreshErrorDescription": { "nullable": true, "type": "string" }, "oauthRefreshFailedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hibernationMode": { "type": "string", "enum": [ "inherit", "enabled", "disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "ownerEmail": { "nullable": true, "type": "string" }, "catalogName": { "nullable": true, "type": "string" }, "users": { "type": "array", "items": { "type": "string" } }, "userDetails": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "email", "createdAt" ], "additionalProperties": false } }, "teamDetails": { "nullable": true, "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "teamId", "name", "createdAt" ], "additionalProperties": false }, "assignedAgents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerId": { "nullable": true, "type": "string" }, "ownerEmail": { "nullable": true, "type": "string" }, "pinned": { "type": "boolean" }, "accessAllTools": { "type": "boolean" }, "organizationId": { "type": "string" } }, "required": [ "id", "name", "agentType", "scope", "ownerId", "ownerEmail", "pinned" ], "additionalProperties": false } }, "secretStorageType": { "type": "string", "enum": [ "vault", "database", "none" ] } }, "required": [ "id", "name", "deploymentName", "catalogId", "serverType", "secretId", "environmentValues", "desktopArguments", "createdByServiceAccountId", "ownerId", "teamId", "scope", "reinstallRequired", "reinstallReason", "localInstallationStatus", "localInstallationError", "oauthRefreshError", "oauthRefreshErrorMessage", "oauthRefreshErrorDescription", "oauthRefreshFailedAt", "lastUsedAt", "hibernationMode", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/mcp_server/{id}/hard-reset": { "post": { "operationId": "hardResetMcpServer", "tags": [ "MCP Server" ], "description": "Destroy and redeploy a stuck MCP server deployment from a clean slate\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:update`](/docs/reference/permissions#mcpServerInstallation:update): Modify installed MCP server configuration", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ] }, "mcpServerId": { "type": "string" }, "physicalDeployment": { "type": "string" }, "resetServerIds": { "type": "array", "items": { "type": "string" } }, "teardown": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "terminated" ] } }, "required": [ "outcome" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "force-killed" ] }, "pods": { "type": "array", "items": { "type": "string" } } }, "required": [ "outcome", "pods" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "unverified" ] }, "reason": { "type": "string" } }, "required": [ "outcome", "reason" ], "additionalProperties": false } ] }, "recreated": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "oneOf": [ { "type": "object", "properties": { "target": { "type": "string", "enum": [ "shared-catalog-deployment" ] }, "catalogId": { "type": "string" } }, "required": [ "target", "catalogId" ], "additionalProperties": false }, { "type": "object", "properties": { "target": { "type": "string", "enum": [ "install-deployment" ] } }, "required": [ "target" ], "additionalProperties": false } ] } ] }, "rebuild": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "ready" ] } }, "required": [ "outcome" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "not-ready" ] }, "reason": { "type": "string" } }, "required": [ "outcome", "reason" ], "additionalProperties": false } ] } }, "required": [ "status", "mcpServerId", "physicalDeployment", "resetServerIds", "teardown", "recreated", "rebuild" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in-progress" ] }, "mcpServerId": { "type": "string" }, "physicalDeployment": { "type": "string" }, "resetServerIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "mcpServerId", "physicalDeployment", "resetServerIds" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_service_unavailable_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:update" ] } } }, "/api/mcp_server/{id}/reload-tools": { "post": { "operationId": "reloadMcpServerTools", "tags": [ "MCP Server" ], "description": "Re-discover an MCP server's tools from the live server and refresh the stored tool catalog without reinstalling\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "updated": { "type": "number" }, "unchanged": { "type": "number" }, "deleted": { "type": "number" } }, "required": [ "created", "updated", "unchanged", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/mcp-tool-calls": { "get": { "operationId": "getMcpToolCalls", "tags": [ "MCP Tool Call" ], "description": "Get MCP tool calls in the active organization with cursor pagination, newest first. [`log:read`](/docs/reference/permissions#log:read) returns rows attributed to the caller. [`log:admin`](/docs/reference/permissions#log:admin) includes every row in the organization. Each row's `sessionId` names the LLM proxy session that issued it, when known, and `llmToolCallId` the model's own id for the call.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) returns rows attributed to the caller. [`log:admin`](/docs/reference/permissions#log:admin) includes every row in the active organization.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "agentId", "required": false, "description": "Filter by agent ID" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by start date (ISO 8601 format)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by end date (ISO 8601 format)" }, { "schema": { "type": "string" }, "in": "query", "name": "mcpServerName", "required": false, "description": "Filter by exact MCP server name" }, { "schema": { "type": "string" }, "in": "query", "name": "userId", "required": false, "description": "Filter by the user the call is attributed to. Ignored without [`log:admin`](/docs/reference/permissions#log:admin), which already scopes the listing to the caller." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "query", "name": "sessionId", "required": false, "description": "Filter by the LLM proxy session that issued the call: calls recorded with that session, and tool calls whose run resolves to it." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerType": { "type": "string", "maxLength": 16 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpServerName": { "type": "string", "maxLength": 255 }, "method": { "type": "string", "maxLength": 255 }, "toolCall": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "namespace": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string", "enum": [ "function", "custom" ] } }, "required": [ "id", "name", "arguments" ], "additionalProperties": false, "description": "Represents a tool call in a provider-agnostic way" }, { "anyOf": [ { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolResult": { "nullable": true }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runId": { "nullable": true, "type": "string" }, "sessionId": { "nullable": true, "type": "string" }, "llmToolCallId": { "nullable": true, "type": "string" }, "authMethod": { "nullable": true, "type": "string", "enum": [ "oauth", "user_token", "org_token", "team_token", "service_account_token", "external_idp", "session" ] }, "oauthClientId": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "chat" ] }, "credentialClientId": { "nullable": true, "type": "string" }, "credentialClientType": { "nullable": true, "type": "string", "enum": [ "identity_provider", "mcp_server", "entra_agent_identity", "okta_ai_agent" ] }, "credentialActorClientId": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "userName": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" } }, "required": [ "id", "ownerType", "agentId", "appId", "mcpServerName", "method", "toolCall", "toolResult", "userId", "serviceAccountId", "runId", "sessionId", "llmToolCallId", "authMethod", "oauthClientId", "source", "credentialClientId", "credentialClientType", "credentialActorClientId", "durationMs", "createdAt", "userName", "appName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` returns rows attributed to the caller. `log:admin` includes every row in the active organization.", "permissions": [ "log:read" ] } } }, "/api/mcp-tool-calls/{mcpToolCallId}": { "get": { "operationId": "getMcpToolCall", "tags": [ "MCP Tool Call" ], "description": "Get an MCP tool call in the active organization by ID. [`log:read`](/docs/reference/permissions#log:read) permits a row attributed to the caller. [`log:admin`](/docs/reference/permissions#log:admin) permits any row in the organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization\n\n[`log:read`](/docs/reference/permissions#log:read) permits a row attributed to the caller. [`log:admin`](/docs/reference/permissions#log:admin) permits any row in the active organization.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "mcpToolCallId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ownerType": { "type": "string", "maxLength": 16 }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mcpServerName": { "type": "string", "maxLength": 255 }, "method": { "type": "string", "maxLength": 255 }, "toolCall": { "nullable": true, "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "namespace": { "type": "string" }, "arguments": { "type": "object", "additionalProperties": {} }, "kind": { "type": "string", "enum": [ "function", "custom" ] } }, "required": [ "id", "name", "arguments" ], "additionalProperties": false, "description": "Represents a tool call in a provider-agnostic way" }, { "anyOf": [ { "type": "object", "properties": { "__encryptedChatSealed": { "type": "string" } }, "required": [ "__encryptedChatSealed" ], "additionalProperties": false }, { "type": "object", "properties": { "__redacted": { "type": "string", "enum": [ "encrypted_chat", "locked_chat", "incognito", "log_content_policy" ] } }, "required": [ "__redacted" ], "additionalProperties": false } ] } ] }, "toolResult": { "nullable": true }, "userId": { "nullable": true, "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runId": { "nullable": true, "type": "string" }, "sessionId": { "nullable": true, "type": "string" }, "llmToolCallId": { "nullable": true, "type": "string" }, "authMethod": { "nullable": true, "type": "string", "enum": [ "oauth", "user_token", "org_token", "team_token", "service_account_token", "external_idp", "session" ] }, "oauthClientId": { "nullable": true, "type": "string" }, "source": { "nullable": true, "type": "string", "enum": [ "api", "chat" ] }, "credentialClientId": { "nullable": true, "type": "string" }, "credentialClientType": { "nullable": true, "type": "string", "enum": [ "identity_provider", "mcp_server", "entra_agent_identity", "okta_ai_agent" ] }, "credentialActorClientId": { "nullable": true, "type": "string" }, "durationMs": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "userName": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" } }, "required": [ "id", "ownerType", "agentId", "appId", "mcpServerName", "method", "toolCall", "toolResult", "userId", "serviceAccountId", "runId", "sessionId", "llmToolCallId", "authMethod", "oauthClientId", "source", "credentialClientId", "credentialClientType", "credentialActorClientId", "durationMs", "createdAt", "userName", "appName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`log:read` permits a row attributed to the caller. `log:admin` permits any row in the active organization.", "permissions": [ "log:read" ] } } }, "/api/members": { "get": { "operationId": "getMembers", "tags": [ "Member" ], "description": "Get all members of the organization with pagination and optional filters\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:read`](/docs/reference/permissions#member:read): View organization members and their roles", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false, "description": "Search by user name or email. Case-insensitive: every whitespace-separated word must appear in the name or the email, in any order, so \"Ada Lovelace\" also matches \"Lovelace, Ada M.\"" }, { "schema": { "type": "string" }, "in": "query", "name": "role", "required": false, "description": "Filter by exact role name" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "image": { "nullable": true, "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "twoFactorEnabled": { "type": "boolean" } }, "required": [ "id", "userId", "name", "email", "image", "role", "createdAt", "twoFactorEnabled" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:read" ] } } }, "/api/members/bulk": { "delete": { "operationId": "bulkDeleteMembers", "tags": [ "Member" ], "description": "Remove accepted members or withdraw pending-signup placeholders in one request. Each target keeps its kind in the partial outcome.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:delete`](/docs/reference/permissions#member:delete): Remove members from the organization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "member" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pendingSignup" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "id" ] } ] }, "description": "Member targets to remove. Duplicates are collapsed by kind and id." } }, "required": [ "targets" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "succeeded": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "member" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pendingSignup" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "id" ], "additionalProperties": false } ] } }, "failed": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "member" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "string" } }, "required": [ "kind", "id", "error" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pendingSignup" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "string" } }, "required": [ "kind", "id", "error" ], "additionalProperties": false } ] } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:delete" ] } } }, "/api/mfiles-vaf-add-on/script": { "get": { "operationId": "getMfilesVafAddOnScript", "tags": [ "Knowledge Bases" ], "description": "Serve the M-Files connector's VAF Add On install bootstrap: a tiny PowerShell script that fetches the static installer and runs it with the server-resolved package source. Identical for every caller — it carries no credentials or per-user state.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/mfiles-vaf-add-on/distribution": { "get": { "operationId": "getMfilesVafAddOnDistribution", "tags": [ "Knowledge Bases" ], "description": "Resolve how the M-Files connector's VAF Add On is distributed to this installation: a verified direct package download URL (the package compiled into this platform image, served by the backend's package route, or a release asset), or null when the install script compiles from source instead. The connector form probes this for its download link.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "packageDownloadUrl": { "nullable": true, "type": "string" } }, "required": [ "packageDownloadUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/mfiles-vaf-add-on/package": { "get": { "operationId": "getMfilesVafAddOnPackage", "tags": [ "Knowledge Bases" ], "description": "Serve the M-Files connector's VAF Add On package compiled into this platform image. 404 when the image carries none.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/microsoft-365-copilot-auth/device/start": { "post": { "operationId": "microsoft365CopilotDeviceAuthStart", "tags": [ "Microsoft 365 Copilot Auth" ], "description": "Start the Entra ID device flow used to connect a Microsoft 365 Copilot account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string" }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "interval": { "type": "number" }, "expiresIn": { "type": "number" } }, "required": [ "deviceCode", "userCode", "verificationUri", "interval", "expiresIn" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/microsoft-365-copilot-auth/device/poll": { "post": { "operationId": "microsoft365CopilotDeviceAuthPoll", "tags": [ "Microsoft 365 Copilot Auth" ], "description": "Poll the Entra ID device flow once; returns the refresh token when the user has authorized\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "slow_down" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete" ] }, "refreshToken": { "type": "string" } }, "required": [ "status", "refreshToken" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/microsoft-365-copilot/chat/completions": { "post": { "operationId": "microsoft365CopilotChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Microsoft 365 Copilot (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/microsoft-365-copilot/{agentId}/chat/completions": { "post": { "operationId": "microsoft365CopilotChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Microsoft 365 Copilot for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" } }, "required": [ "model", "messages" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string", "enum": [ "chat.completion" ] }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "created", "model", "object" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/microsoft-365-copilot/models": { "get": { "operationId": "microsoft365CopilotListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List Microsoft 365 Copilot models (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/microsoft-365-copilot/{agentId}/models": { "get": { "operationId": "microsoft365CopilotListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List Microsoft 365 Copilot models (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/minimax/chat/completions": { "post": { "operationId": "minimaxChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with MiniMax (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MinimaxChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MinimaxChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/minimax/{agentId}/chat/completions": { "post": { "operationId": "minimaxChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with MiniMax for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MinimaxChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MinimaxChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/mistral/embeddings": { "post": { "operationId": "mistralEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Mistral (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/mistral/{agentId}/embeddings": { "post": { "operationId": "mistralEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Mistral for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/mistral/chat/completions": { "post": { "operationId": "mistralChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Mistral (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MistralChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/mistral/{agentId}/chat/completions": { "post": { "operationId": "mistralChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Mistral for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MistralChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/model-pools": { "get": { "operationId": "getModelPools", "tags": [ "Model Pools" ], "description": "List the organization's model pools with their members, and which members are benched after a failure\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:read`](/docs/reference/permissions#llmModel:read): View synced LLM models and capabilities", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "routingStrategy": { "type": "string", "enum": [ "weighted", "least-tokens" ] }, "streamTimeoutSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "timeoutSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cooldownSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } }, "additionalProperties": false }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "poolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string" }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "weight": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } }, "additionalProperties": false }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "providerApiKeyName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "benchedUntil": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "benchReason": { "nullable": true, "type": "string" } }, "required": [ "id", "poolId", "providerApiKeyId", "modelId", "priority", "weight", "enabled", "retrySettings", "createdAt", "providerApiKeyName", "provider", "benchedUntil", "benchReason" ], "additionalProperties": false } }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "name", "routingStrategy", "streamTimeoutSeconds", "timeoutSeconds", "cooldownSeconds", "retrySettings", "createdAt", "updatedAt", "members", "virtualApiKeyIds" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:read" ] } }, "post": { "operationId": "createModelPool", "tags": [ "Model Pools" ], "description": "Create a model pool: a model name served by provider keys on any provider, each with its own model id, tried by priority and split by weight\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:update`](/docs/reference/permissions#llmModel:update): Sync the model catalog and see every model, including ones not shared with you", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "routingStrategy": { "type": "string", "enum": [ "weighted", "least-tokens" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "members": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string", "minLength": 1, "maxLength": 512 }, "priority": { "default": 1, "type": "integer", "minimum": 1, "maximum": 100 }, "weight": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000 }, "enabled": { "default": true, "type": "boolean" }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } } }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } } } }, "required": [ "providerApiKeyId", "modelId" ] } }, "streamTimeoutSeconds": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1800 }, "timeoutSeconds": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1800 }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } } }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } } }, "cooldownSeconds": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 3600 } }, "required": [ "name", "members" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "routingStrategy": { "type": "string", "enum": [ "weighted", "least-tokens" ] }, "streamTimeoutSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "timeoutSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cooldownSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } }, "additionalProperties": false }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "poolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string" }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "weight": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } }, "additionalProperties": false }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "providerApiKeyName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] } }, "required": [ "id", "poolId", "providerApiKeyId", "modelId", "priority", "weight", "enabled", "retrySettings", "createdAt", "providerApiKeyName", "provider" ], "additionalProperties": false } }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "name", "routingStrategy", "streamTimeoutSeconds", "timeoutSeconds", "cooldownSeconds", "retrySettings", "createdAt", "updatedAt", "members", "virtualApiKeyIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:update" ] } } }, "/api/model-pools/available": { "get": { "operationId": "getAvailableModelPools", "tags": [ "Model Pools" ], "description": "List the model pools the current user can pick in chat: those with a member on a key the user may use\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmProviderApiKey:read`](/docs/reference/permissions#llmProviderApiKey:read): Open LLM provider API keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "providers": { "type": "array", "items": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] } } }, "required": [ "id", "name", "providers" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmProviderApiKey:read" ] } } }, "/api/model-pools/{id}": { "put": { "operationId": "updateModelPool", "tags": [ "Model Pools" ], "description": "Replace a model pool's settings and members\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:update`](/docs/reference/permissions#llmModel:update): Sync the model catalog and see every model, including ones not shared with you", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "routingStrategy": { "type": "string", "enum": [ "weighted", "least-tokens" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "members": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string", "minLength": 1, "maxLength": 512 }, "priority": { "default": 1, "type": "integer", "minimum": 1, "maximum": 100 }, "weight": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000 }, "enabled": { "default": true, "type": "boolean" }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } } }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } } } }, "required": [ "providerApiKeyId", "modelId" ] } }, "streamTimeoutSeconds": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1800 }, "timeoutSeconds": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 1800 }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } } }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } } }, "cooldownSeconds": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 3600 } }, "required": [ "name", "members" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "routingStrategy": { "type": "string", "enum": [ "weighted", "least-tokens" ] }, "streamTimeoutSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "timeoutSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cooldownSeconds": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } }, "additionalProperties": false }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "poolId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelId": { "type": "string" }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "weight": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "enabled": { "type": "boolean" }, "retrySettings": { "nullable": true, "type": "object", "properties": { "numRetries": { "type": "integer", "minimum": 0, "maximum": 10 }, "retryPolicy": { "type": "object", "properties": { "connectionError": { "type": "integer", "minimum": 0, "maximum": 10 }, "timeoutError": { "type": "integer", "minimum": 0, "maximum": 10 }, "rateLimitError": { "type": "integer", "minimum": 0, "maximum": 10 }, "internalServerError": { "type": "integer", "minimum": 0, "maximum": 10 } }, "additionalProperties": false }, "initialDelayMs": { "type": "integer", "minimum": 100, "maximum": 8000 }, "maxDelayMs": { "type": "integer", "minimum": 100, "maximum": 60000 } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "providerApiKeyName": { "type": "string" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] } }, "required": [ "id", "poolId", "providerApiKeyId", "modelId", "priority", "weight", "enabled", "retrySettings", "createdAt", "providerApiKeyName", "provider" ], "additionalProperties": false } }, "virtualApiKeyIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "name", "routingStrategy", "streamTimeoutSeconds", "timeoutSeconds", "cooldownSeconds", "retrySettings", "createdAt", "updatedAt", "members", "virtualApiKeyIds" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:update" ] } }, "delete": { "operationId": "deleteModelPool", "tags": [ "Model Pools" ], "description": "Delete a model pool\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmModel:update`](/docs/reference/permissions#llmModel:update): Sync the model catalog and see every model, including ones not shared with you", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmModel:update" ] } } }, "/v1/unified-model/images/edits": { "post": { "operationId": "modelRouterImageEditsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Edit images through a mapped OpenAI, Azure or Gemini image model using bounded multipart reference images and an optional mask.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "anyOf": [ { "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, { "type": "null" } ] }, "background": { "anyOf": [ { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string", "enum": [ "url", "b64_json" ] }, { "type": "null" } ] }, "user": { "type": "string" }, "safety_identifier": { "type": [ "string", "null" ] }, "n": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "output_compression": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ] }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "null" } ] }, "image": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 16, "description": "PNG/JPEG/WebP reference files, each smaller than 50 MiB." }, "mask": { "type": "string", "format": "binary", "description": "Optional PNG alpha mask smaller than 4 MiB, matching the first image dimensions." } }, "required": [ "model", "prompt", "image" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/{agentId}/images/edits": { "post": { "operationId": "modelRouterImageEditsWithAgent", "tags": [ "LLM Proxy" ], "description": "Edit images through a mapped OpenAI, Azure or Gemini image model using bounded multipart reference images and an optional mask.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "anyOf": [ { "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, { "type": "null" } ] }, "background": { "anyOf": [ { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string", "enum": [ "url", "b64_json" ] }, { "type": "null" } ] }, "user": { "type": "string" }, "safety_identifier": { "type": [ "string", "null" ] }, "n": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "output_compression": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ] }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "null" } ] }, "image": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 16, "description": "PNG/JPEG/WebP reference files, each smaller than 50 MiB." }, "mask": { "type": "string", "format": "binary", "description": "Optional PNG alpha mask smaller than 4 MiB, matching the first image dimensions." } }, "required": [ "model", "prompt", "image" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/audio/speech": { "post": { "operationId": "modelRouterAudioSpeechWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Use mapped Azure or OpenAI credentials for governed native audio responses. Raw audio is excluded from interaction logs.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "input": { "type": "string", "minLength": 1, "maxLength": 4096 }, "voice": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ] } }, "required": [ "model", "input", "voice" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/unified-model/{agentId}/audio/speech": { "post": { "operationId": "modelRouterAudioSpeechWithAgent", "tags": [ "LLM Proxy" ], "description": "Use mapped Azure or OpenAI credentials for governed native audio responses. Raw audio is excluded from interaction logs.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "input": { "type": "string", "minLength": 1, "maxLength": 4096 }, "voice": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ] } }, "required": [ "model", "input", "voice" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/unified-model/audio/transcriptions": { "post": { "operationId": "modelRouterAudioTranscriptionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Use mapped Azure or OpenAI credentials for governed native audio responses. Raw audio is excluded from interaction logs.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/unified-model/{agentId}/audio/transcriptions": { "post": { "operationId": "modelRouterAudioTranscriptionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Use mapped Azure or OpenAI credentials for governed native audio responses. Raw audio is excluded from interaction logs.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/unified-model/audio/translations": { "post": { "operationId": "modelRouterAudioTranslationsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Use mapped Azure or OpenAI credentials for governed native audio responses. Raw audio is excluded from interaction logs.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/unified-model/{agentId}/audio/translations": { "post": { "operationId": "modelRouterAudioTranslationsWithAgent", "tags": [ "LLM Proxy" ], "description": "Use mapped Azure or OpenAI credentials for governed native audio responses. Raw audio is excluded from interaction logs.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/unified-model/images/generations": { "post": { "operationId": "modelRouterImagesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Generate images through the OpenAI-compatible Unified Model API. Unsupported provider parameters and streaming are rejected.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/{agentId}/images/generations": { "post": { "operationId": "modelRouterImagesWithAgent", "tags": [ "LLM Proxy" ], "description": "Generate images through the OpenAI-compatible Unified Model API. Unsupported provider parameters and streaming are rejected.\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/models": { "get": { "operationId": "modelRouterListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List OpenAI-compatible model ids available through the Unified Model API (default LLM proxy)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" }, "capabilities": { "type": "object", "properties": { "context_length": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_output_tokens": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "output_modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supports_tools": { "nullable": true, "type": "boolean" }, "supports_vision": { "nullable": true, "type": "boolean" }, "supports_reasoning_effort": { "nullable": true, "type": "boolean" }, "supported_reasoning_efforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "supported_endpoints": { "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses", "/embeddings" ] } } }, "required": [ "context_length", "max_output_tokens", "input_modalities", "output_modalities", "supports_tools", "supports_vision", "supports_reasoning_effort", "supported_reasoning_efforts", "supported_endpoints" ], "additionalProperties": false } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/{agentId}/models": { "get": { "operationId": "modelRouterListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List OpenAI-compatible model ids available through the Unified Model API (specific attribution Agent)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" }, "capabilities": { "type": "object", "properties": { "context_length": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_output_tokens": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "input_modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio", "video", "pdf" ] } }, "output_modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "image", "audio" ] } }, "supports_tools": { "nullable": true, "type": "boolean" }, "supports_vision": { "nullable": true, "type": "boolean" }, "supports_reasoning_effort": { "nullable": true, "type": "boolean" }, "supported_reasoning_efforts": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } }, "supported_endpoints": { "type": "array", "items": { "type": "string", "enum": [ "/chat/completions", "/responses", "/embeddings" ] } } }, "required": [ "context_length", "max_output_tokens", "input_modalities", "output_modalities", "supports_tools", "supports_vision", "supports_reasoning_effort", "supported_reasoning_efforts", "supported_endpoints" ], "additionalProperties": false } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/responses": { "post": { "operationId": "modelRouterResponsesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a response through the OpenAI-compatible Unified Model API (default LLM proxy)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/{agentId}/responses": { "post": { "operationId": "modelRouterResponsesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a response through the OpenAI-compatible Unified Model API (specific attribution Agent)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/embeddings": { "post": { "operationId": "modelRouterEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings through the OpenAI-compatible Unified Model API (default LLM proxy)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/{agentId}/embeddings": { "post": { "operationId": "modelRouterEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings through the OpenAI-compatible Unified Model API (specific attribution Agent)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/chat/completions": { "post": { "operationId": "modelRouterChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion through the OpenAI-compatible Unified Model API (default LLM proxy)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" }, "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "cachedContent": { "type": "string" } }, "required": [ "model", "messages" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string" }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "model" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/unified-model/{agentId}/chat/completions": { "post": { "operationId": "modelRouterChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion through the OpenAI-compatible Unified Model API (specific attribution Agent)\n\nAuthentication:\n\nRequires a mapped standard Virtual API Key or LLM OAuth access token, sent as a Bearer token. Provider API keys, passthrough keys, and external identity-provider JWTs are not accepted. See [Unified Model API](/docs/llm-proxy/unified-model).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "developer" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L936" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } } ] }, "role": { "type": "string", "enum": [ "system" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1318" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "input_audio" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "input_audio": { "type": "object", "properties": { "data": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "mp3" ] } }, "required": [ "data", "format" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L792" } }, "required": [ "type", "input_audio" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L782" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "file" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "file": { "type": "object", "properties": { "file_data": { "type": "string" }, "file_id": { "type": "string" }, "filename": { "type": "string" } }, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L732" } }, "required": [ "type", "file" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L722" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L711" } } ] }, "role": { "type": "string", "enum": [ "user" ] }, "name": { "type": "string" } }, "required": [ "content", "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1434" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "audio": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "content": { "nullable": true, "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" } }, { "type": "array", "items": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L805" } } ] }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ] }, "name": { "type": "string" }, "reasoning_content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "tool_calls": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L374" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] } }, "required": [ "type", "text" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L821" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "image_url" ] }, "prompt_cache_breakpoint": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "explicit" ] } }, "required": [ "mode" ] }, "image_url": { "type": "object", "properties": { "url": { "type": "string" }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "required": [ "url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L765" } }, "required": [ "type", "image_url" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L755" } ] } } ] }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content", "tool_call_id" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1413" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "role": { "type": "string", "enum": [ "function" ] }, "content": { "nullable": true, "type": "string" }, "name": { "type": "string" } }, "required": [ "role", "content", "name" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L968" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1186" } }, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "type", "definition", "syntax" ] } ] } }, "required": [ "type", "name" ], "description": "\n A custom tool in the flat Responses-API shape ('name'/'format' at the top\n level, grammar fields inlined) rather than Chat Completions' nested 'custom'\n wrapper. Some clients (e.g. Cursor's ApplyPatch tool) send this shape to\n /chat/completions and OpenAI accepts it, so the proxy must too.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/responses/responses.ts (CustomTool)\n " } ], "description": "\n A function tool that can be used to generate a response.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1392\n " } }, "tool_choice": { "anyOf": [ { "type": "string", "enum": [ "none", "auto", "required" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "allowed_tools" ] }, "allowed_tools": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "required" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n auto allows the model to pick from among the allowed tools and generate a\n message.\n\n required requires the model to call one or more of the allowed tools.\n " }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ], "description": "https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L174" } }, "required": [ "type", "function" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L988" } }, "description": "A list of tool definitions that the model should be allowed to call" } }, "required": [ "mode", "tools" ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1455" } }, "required": [ "type", "allowed_tools" ], "description": "\n Constrains the tools available to the model to a pre-defined set.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L359\n " }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "required": [ "type", "function" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific function.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1207-L1214\n " }, { "type": "object", "properties": { "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls" }, "description": { "description": "Optional description of the custom tool, used to provide more context", "type": "string" }, "format": { "description": "The input format for the custom tool. Default is unconstrained text.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`" } }, "required": [ "type" ], "description": "Unconstrained free-form text" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "grammar" ] }, "grammar": { "type": "object", "properties": { "definition": { "type": "string", "description": "The grammar definition" }, "syntax": { "type": "string", "enum": [ "lark", "regex" ], "description": "The syntax of the grammar definition" } }, "required": [ "definition", "syntax" ], "description": "Your chosen grammar" } }, "required": [ "type", "grammar" ] } ] } }, "required": [ "name" ] } }, "required": [ "type", "custom" ], "description": "\n Specifies a tool the model should use. Use to force the model to call a specific custom tool.\n\n https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1229-L1236\n " } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1405" }, "response_format": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_object" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_schema" ] }, "json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] } ] }, "temperature": { "nullable": true, "type": "number" }, "max_tokens": { "nullable": true, "type": "number" }, "max_completion_tokens": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "prompt_cache_key": { "nullable": true, "type": "string" }, "prompt_cache_retention": { "nullable": true, "type": "string", "enum": [ "in-memory", "24h" ] }, "prompt_cache_options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "implicit", "explicit" ] }, "ttl": { "type": "string" } }, "additionalProperties": {} }, "reasoning_effort": { "nullable": true, "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "modalities": { "nullable": true, "type": "array", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "audio": { "nullable": true, "type": "object", "properties": { "voice": { "type": "string" }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ] } }, "required": [ "voice", "format" ] }, "stream": { "nullable": true, "type": "boolean" }, "stream_options": { "nullable": true, "type": "object", "properties": { "include_usage": { "type": "boolean" } } }, "user": { "type": "string" }, "cache_control": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ephemeral" ] }, "ttl": { "type": "string", "enum": [ "5m", "1h" ] } }, "required": [ "type" ] }, "cachedContent": { "type": "string" } }, "required": [ "model", "messages" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "finish_reason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, { "type": "string" } ] }, "index": { "type": "number" }, "logprobs": { "nullable": true }, "message": { "type": "object", "properties": { "content": { "nullable": true, "type": "string" }, "refusal": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "assistant" ] }, "annotations": { "nullable": true, "type": "array", "items": {} }, "audio": { "nullable": true }, "function_call": { "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L431", "nullable": true, "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false }, "reasoning_content": { "nullable": true, "type": "string" }, "tool_calls": { "nullable": true, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] }, "function": { "type": "object", "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } }, "required": [ "arguments", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1165" } }, "required": [ "id", "type", "function" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1144" }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "object", "properties": { "input": { "type": "string" }, "name": { "type": "string" } }, "required": [ "input", "name" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1128" } }, "required": [ "id", "type", "custom" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1107" } ], "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1197" } } }, "required": [ "role" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L1000" } }, "required": [ "finish_reason", "message" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/v6.0.0/src/resources/chat/completions/completions.ts#L311" } }, "created": { "type": "number" }, "model": { "type": "string" }, "object": { "type": "string" }, "server_tier": { "type": "string" }, "system_fingerprint": { "nullable": true, "type": "string" }, "usage": { "type": "object", "properties": { "completion_tokens": { "type": "number" }, "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" }, "completion_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L144" }, "prompt_tokens_details": { "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L173" } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "additionalProperties": false, "description": "https://github.com/openai/openai-node/blob/master/src/resources/completions.ts#L113" } }, "required": [ "id", "choices", "model" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/oauth-clients/labels/keys": { "get": { "operationId": "oauthClientLabelKeys", "tags": [ "OAuth Clients" ], "description": "Get all label keys used by OAuth clients\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`oauthClient:read`](/docs/reference/permissions#oauthClient:read): Open OAuth client registrations", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "oauthClient:read" ] } } }, "/api/oauth-clients/labels/values": { "get": { "operationId": "oauthClientLabelValues", "tags": [ "OAuth Clients" ], "description": "Get all label values used by OAuth clients\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`oauthClient:read`](/docs/reference/permissions#oauthClient:read): Open OAuth client registrations", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "oauthClient:read" ] } } }, "/api/oauth-clients": { "get": { "operationId": "getOauthClients", "tags": [ "OAuth Clients" ], "description": "List managed OAuth clients and their enabled API capabilities\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] }, "in": "query", "name": "capability", "required": false, "description": "Include clients that grant this API capability, including clients with other capabilities." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "providerApiKeyId", "required": false }, { "schema": { "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "in": "query", "name": "grantType", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "applicableTo", "required": false, "description": "Only clients that can reach this agent or MCP gateway: authorization-code clients, and client-credentials clients that list it, with the target's protocol (MCP for a gateway, A2A for an agent)." }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "organizationId": { "type": "string" }, "grantType": { "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean" }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "modelPoolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "type": "boolean" } }, "required": [ "id", "clientId", "serviceAccountId", "name", "organizationId", "grantType", "providerApiKeys", "redirectUris", "disabled", "authorId", "authorName", "createdBy", "labels", "modelPoolIds", "autoRouterIds", "createdAt", "updatedAt", "billingTeam", "spendCap", "icon", "scopes", "allowedGatewayIds", "includeFutureProviders" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createOauthClient", "tags": [ "OAuth Clients" ], "description": "Create an OAuth client and return its client secret once\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`oauthClient:create`](/docs/reference/permissions#oauthClient:create): Create OAuth client registrations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "icon": { "description": "An emoji, a logo id or an image data URL shown beside the name. Omit on update to keep it; null clears it.", "nullable": true, "type": "string", "maxLength": 1048576 }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scopes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "grantType": { "default": "client_credentials", "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ] } }, "modelPoolIds": { "description": "Model pools the client may call by name without mapping one of their members. Omit on update to keep them. Only applies to client_credentials clients.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "description": "Auto routers the client may call by name, on the routers' own provider keys. Omit on update to keep them. Only applies to client_credentials clients.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "description": "Use current and future shared primary provider keys, with selected keys as overrides. Defaults to false on creation; omit on update to preserve the mode. Only valid for client_credentials with LLM Proxy access.", "type": "boolean" }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "billingTeamId": { "description": "Team a client_credentials client's spend is charged to. Omit to keep it; null stops billing a team. Signed-in users of an authorization_code client pay for themselves.", "nullable": true, "type": "string" }, "spendCap": { "description": "Spend cap for the whole client, stored as a token_cost limit on it. Omit to keep it; null removes it.", "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] } }, "required": [ "limitValue", "cleanupInterval" ] }, "initialGrants": { "description": "Who else starts with access, beside the creator who always gets full access.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "organizationId": { "type": "string" }, "grantType": { "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean" }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "modelPoolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "type": "boolean" }, "clientSecret": { "type": "string" } }, "required": [ "id", "clientId", "serviceAccountId", "name", "organizationId", "grantType", "providerApiKeys", "redirectUris", "disabled", "authorId", "authorName", "createdBy", "labels", "modelPoolIds", "autoRouterIds", "createdAt", "updatedAt", "billingTeam", "spendCap", "icon", "scopes", "allowedGatewayIds", "includeFutureProviders", "clientSecret" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "oauthClient:create" ] } } }, "/api/oauth-clients/{id}": { "get": { "operationId": "getOauthClient", "tags": [ "OAuth Clients" ], "description": "Get one OAuth client and its enabled API capabilities\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "organizationId": { "type": "string" }, "grantType": { "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean" }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "modelPoolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "type": "boolean" } }, "required": [ "id", "clientId", "serviceAccountId", "name", "organizationId", "grantType", "providerApiKeys", "redirectUris", "disabled", "authorId", "authorName", "createdBy", "labels", "modelPoolIds", "autoRouterIds", "createdAt", "updatedAt", "billingTeam", "spendCap", "icon", "scopes", "allowedGatewayIds", "includeFutureProviders" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateOauthClient", "tags": [ "OAuth Clients" ], "description": "Update an OAuth client\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "icon": { "description": "An emoji, a logo id or an image data URL shown beside the name. Omit on update to keep it; null clears it.", "nullable": true, "type": "string", "maxLength": 1048576 }, "serviceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scopes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "grantType": { "default": "client_credentials", "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ] } }, "modelPoolIds": { "description": "Model pools the client may call by name without mapping one of their members. Omit on update to keep them. Only applies to client_credentials clients.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "description": "Auto routers the client may call by name, on the routers' own provider keys. Omit on update to keep them. Only applies to client_credentials clients.", "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "description": "Use current and future shared primary provider keys, with selected keys as overrides. Defaults to false on creation; omit on update to preserve the mode. Only valid for client_credentials with LLM Proxy access.", "type": "boolean" }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "billingTeamId": { "description": "Team a client_credentials client's spend is charged to. Omit to keep it; null stops billing a team. Signed-in users of an authorization_code client pay for themselves.", "nullable": true, "type": "string" }, "spendCap": { "description": "Spend cap for the whole client, stored as a token_cost limit on it. Omit to keep it; null removes it.", "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] } }, "required": [ "limitValue", "cleanupInterval" ] } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "organizationId": { "type": "string" }, "grantType": { "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean" }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "modelPoolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "type": "boolean" } }, "required": [ "id", "clientId", "serviceAccountId", "name", "organizationId", "grantType", "providerApiKeys", "redirectUris", "disabled", "authorId", "authorName", "createdBy", "labels", "modelPoolIds", "autoRouterIds", "createdAt", "updatedAt", "billingTeam", "spendCap", "icon", "scopes", "allowedGatewayIds", "includeFutureProviders" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteOauthClient", "tags": [ "OAuth Clients" ], "description": "Delete an OAuth client\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/oauth-clients/{id}/rotate-secret": { "post": { "operationId": "rotateOauthClientSecret", "tags": [ "OAuth Clients" ], "description": "Rotate an OAuth client's client secret\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "serviceAccountId": { "nullable": true, "type": "string" }, "name": { "type": "string" }, "organizationId": { "type": "string" }, "grantType": { "type": "string", "enum": [ "client_credentials", "authorization_code" ] }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "boolean" }, "authorId": { "nullable": true, "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "modelPoolIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false }, "icon": { "nullable": true, "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp", "a2a", "llm:proxy" ] } }, "allowedGatewayIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "includeFutureProviders": { "type": "boolean" }, "clientSecret": { "type": "string" } }, "required": [ "id", "clientId", "serviceAccountId", "name", "organizationId", "grantType", "providerApiKeys", "redirectUris", "disabled", "authorId", "authorName", "createdBy", "labels", "modelPoolIds", "autoRouterIds", "createdAt", "updatedAt", "billingTeam", "spendCap", "icon", "scopes", "allowedGatewayIds", "includeFutureProviders", "clientSecret" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/oauth-clients/bulk": { "delete": { "operationId": "bulkDeleteOauthClients", "tags": [ "OAuth Clients" ], "description": "Delete several OAuth clients in one request. Each id is authorized exactly as the single-client delete authorizes its own, so a client the caller cannot see or manage is reported in `failed` while the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/oauth/initiate": { "post": { "operationId": "initiateOAuth", "tags": [ "OAuth" ], "description": "Initiate OAuth flow for MCP server installation\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serverId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "catalogId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "state": { "type": "string" } }, "required": [ "authorizationUrl", "state" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/oauth/callback": { "post": { "operationId": "handleOAuthCallback", "tags": [ "OAuth" ], "description": "Handle OAuth callback and exchange code for tokens\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "iss": { "type": "string" }, "state": { "type": "string" } }, "required": [ "code", "state" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "number" }, "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "success", "catalogId", "name", "accessToken", "secretId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/.well-known/oauth-protected-resource/{*}": { "get": { "tags": [ "OAuth" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } } }, "required": [ "resource", "authorization_servers", "scopes_supported", "bearer_methods_supported" ], "additionalProperties": false } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "OAuth" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "jwks_uri": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "client_id_metadata_document_supported": { "type": "boolean" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "jwks_uri", "response_types_supported", "grant_types_supported", "token_endpoint_auth_methods_supported", "code_challenge_methods_supported", "scopes_supported", "client_id_metadata_document_supported" ], "additionalProperties": false } } } } } } }, "/v1/ollama-native/api/chat": { "post": { "operationId": "ollamaNativeChatWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Ollama native /api/chat (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaNativeChatRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Ollama (typically not required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaNativeChatResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/ollama-native/{agentId}/api/chat": { "post": { "operationId": "ollamaNativeChatWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Ollama native /api/chat for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaNativeChatRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Ollama (typically not required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaNativeChatResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/ollama/embeddings": { "post": { "operationId": "ollamaEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Ollama (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/ollama/{agentId}/embeddings": { "post": { "operationId": "ollamaEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Ollama for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/ollama/chat/completions": { "post": { "operationId": "ollamaChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Ollama (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Ollama (typically not required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/ollama/{agentId}/chat/completions": { "post": { "operationId": "ollamaChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Ollama for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for Ollama (typically not required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OllamaChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/onboarding/seen-nav-items": { "get": { "operationId": "getOnboardingSeenNavItems", "tags": [ "Onboarding" ], "description": "Get the onboarding nav items (red-dot nudges) the current user has already visited\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "markOnboardingNavItemsSeen", "tags": [ "Onboarding" ], "description": "Mark onboarding nav items (red-dot nudges) as visited for the current user; idempotent\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/onboarding/survey-eligibility": { "get": { "operationId": "getOnboardingSurveyEligibility", "tags": [ "Onboarding" ], "description": "Whether the first-login onboarding survey should be shown: unlicensed instance, no LLM/MCP activity yet, not already submitted for the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "eligible": { "type": "boolean" } }, "required": [ "eligible" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/onboarding/survey": { "post": { "operationId": "submitOnboardingSurvey", "tags": [ "Onboarding" ], "description": "Submit the first-login onboarding survey; forwarded to the website and recorded once per organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 200 }, "workEnvironment": { "type": "string", "minLength": 1, "maxLength": 200 }, "referralSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "workEmail": { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "role", "workEnvironment", "referralSource" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/v1/openai/audio/speech": { "post": { "operationId": "openAiAudioSpeechWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Generate native audio bytes or audio SSE through the governed proxy. Usage and audio pricing may be unavailable.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "input": { "type": "string", "minLength": 1, "maxLength": 4096 }, "voice": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ] } }, "required": [ "model", "input", "voice" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/openai/{agentId}/audio/speech": { "post": { "operationId": "openAiAudioSpeechWithAgent", "tags": [ "LLM Proxy" ], "description": "Generate native audio bytes or audio SSE through the governed proxy. Usage and audio pricing may be unavailable.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "input": { "type": "string", "minLength": 1, "maxLength": 4096 }, "voice": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id" ] } ] }, "instructions": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 }, "stream_format": { "type": "string", "enum": [ "audio", "sse" ] } }, "required": [ "model", "input", "voice" ], "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/openai/audio/transcriptions": { "post": { "operationId": "openAiAudioTranscriptionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/openai/{agentId}/audio/transcriptions": { "post": { "operationId": "openAiAudioTranscriptionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/openai/audio/translations": { "post": { "operationId": "openAiAudioTranslationsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/openai/{agentId}/audio/translations": { "post": { "operationId": "openAiAudioTranslationsWithAgent", "tags": [ "LLM Proxy" ], "description": "Upload multipart audio with file and model fields. Returns the provider's native transcript bytes or supported SSE. Raw audio is never retained in interaction logs.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 64 }, "prompt": { "type": "string", "maxLength": 16384 }, "response_format": { "type": "string", "enum": [ "json", "text", "srt", "verbose_json", "vtt", "diarized_json" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "stream": { "type": "boolean" }, "include": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "timestamp_granularities": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "word", "segment" ] } }, "known_speaker_names": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "known_speaker_references": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "languages": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "chunking_strategy": { "anyOf": [ { "type": "string", "enum": [ "auto" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server_vad" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "prefix_padding_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "silence_duration_ms": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false } ] }, "file": { "type": "string", "format": "binary", "description": "Audio file (maximum 25 MiB)" } }, "required": [ "model", "file" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/openai/images/generations": { "post": { "operationId": "openAiImagesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Generate images with OpenAI\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/images/generations": { "post": { "operationId": "openAiImagesWithAgent", "tags": [ "LLM Proxy" ], "description": "Generate images with OpenAI\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "nullable": true, "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, "quality": { "nullable": true, "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, "background": { "nullable": true, "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, "output_format": { "nullable": true, "type": "string", "enum": [ "png", "jpeg", "webp" ] }, "response_format": { "nullable": true, "type": "string", "enum": [ "url", "b64_json" ] }, "user": { "type": "string" }, "safety_identifier": { "nullable": true, "type": "string" }, "n": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 10 }, "output_compression": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 100 }, "moderation": { "nullable": true, "type": "string", "enum": [ "auto", "low" ] }, "style": { "nullable": true, "type": "string", "enum": [ "vivid", "natural" ] }, "stream": { "nullable": true, "type": "boolean", "enum": [ false ] } }, "required": [ "model", "prompt" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/images/edits": { "post": { "operationId": "openAiImageEditsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Edit images with OpenAI using bounded multipart image inputs and an optional PNG mask. Returns a complete image response; streaming is unsupported.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "anyOf": [ { "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, { "type": "null" } ] }, "background": { "anyOf": [ { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string", "enum": [ "url", "b64_json" ] }, { "type": "null" } ] }, "user": { "type": "string" }, "safety_identifier": { "type": [ "string", "null" ] }, "n": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "output_compression": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ] }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "null" } ] }, "image": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 16, "description": "PNG/JPEG/WebP reference files, each smaller than 50 MiB." }, "mask": { "type": "string", "format": "binary", "description": "Optional PNG alpha mask smaller than 4 MiB, matching the first image dimensions." } }, "required": [ "model", "prompt", "image" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/images/edits": { "post": { "operationId": "openAiImageEditsWithAgent", "tags": [ "LLM Proxy" ], "description": "Edit images with OpenAI using bounded multipart image inputs and an optional PNG mask. Returns a complete image response; streaming is unsupported.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "size": { "anyOf": [ { "type": "string", "pattern": "^(auto|[1-9]\\d{0,4}x[1-9]\\d{0,4})$" }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "auto", "low", "medium", "high", "xhigh", "max", "standard", "hd" ] }, { "type": "null" } ] }, "background": { "anyOf": [ { "type": "string", "enum": [ "auto", "transparent", "opaque" ] }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "jpeg", "webp" ] }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string", "enum": [ "url", "b64_json" ] }, { "type": "null" } ] }, "user": { "type": "string" }, "safety_identifier": { "type": [ "string", "null" ] }, "n": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10 }, { "type": "null" } ] }, "output_compression": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ] }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "enum": [ false ] }, { "type": "null" } ] }, "image": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 16, "description": "PNG/JPEG/WebP reference files, each smaller than 50 MiB." }, "mask": { "type": "string", "format": "binary", "description": "Optional PNG alpha mask smaller than 4 MiB, matching the first image dimensions." } }, "required": [ "model", "prompt", "image" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number" }, "model": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "b64_json": { "type": "string" }, "url": { "type": "string" }, "revised_prompt": { "type": "string" } }, "additionalProperties": false } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {} } }, "required": [ "created" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/embeddings": { "post": { "operationId": "openAiEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with OpenAI (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/embeddings": { "post": { "operationId": "openAiEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with OpenAI for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string" } ] }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/responses": { "post": { "operationId": "openAiResponsesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with OpenAI (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/responses": { "post": { "operationId": "openAiResponsesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with OpenAI for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/responses/compact": { "post": { "operationId": "openAiResponsesCompactWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Compact an OpenAI response (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "previous_response_id": { "nullable": true, "type": "string" }, "prompt_cache_key": { "nullable": true, "type": "string" } }, "required": [ "model" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response.compaction" ] }, "created_at": { "type": "number" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "output", "usage" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/responses/compact": { "post": { "operationId": "openAiResponsesCompactWithAgent", "tags": [ "LLM Proxy" ], "description": "Compact an OpenAI response for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "previous_response_id": { "nullable": true, "type": "string" }, "prompt_cache_key": { "nullable": true, "type": "string" } }, "required": [ "model" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response.compaction" ] }, "created_at": { "type": "number" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "output", "usage" ], "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/chat/completions": { "post": { "operationId": "openAiChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with OpenAI (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/chat/completions": { "post": { "operationId": "openAiChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with OpenAI for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/models": { "get": { "operationId": "openAiListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List OpenAI models (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } }, "models": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "slug", "display_name" ], "additionalProperties": {} } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openai/{agentId}/models": { "get": { "operationId": "openAiListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List OpenAI models (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } }, "models": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "slug", "display_name" ], "additionalProperties": {} } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/openai-codex-auth/device/start": { "post": { "operationId": "openaiCodexDeviceAuthStart", "tags": [ "OpenAI Codex Auth" ], "description": "Start the ChatGPT/Codex OAuth device flow used to connect a ChatGPT subscription as an OpenAI provider credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceAuthId": { "type": "string" }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "interval": { "type": "number" }, "expiresIn": { "type": "number" } }, "required": [ "deviceAuthId", "userCode", "verificationUri", "interval", "expiresIn" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/openai-codex-auth/device/poll": { "post": { "operationId": "openaiCodexDeviceAuthPoll", "tags": [ "OpenAI Codex Auth" ], "description": "Poll the ChatGPT/Codex OAuth device flow once; returns the encoded provider credential when the user has authorized\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceAuthId": { "type": "string", "minLength": 1 }, "userCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceAuthId", "userCode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "slow_down" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete" ] }, "credential": { "type": "string" } }, "required": [ "status", "credential" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/openappa/annotators/archestra": { "post": { "operationId": "annotateOpenappaToolWithArchestra", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "default": "annotation", "type": "string", "enum": [ "annotation", "sanitizer", "authority" ] }, "system": { "type": "string" }, "input": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "attribution": { "type": "object", "properties": { "root": { "type": "string" }, "trajectory": { "type": "string" }, "call_id": { "type": "string" } }, "required": [ "root", "trajectory" ] } }, "required": [ "system", "input", "schema" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/openappa/batteries": { "get": { "operationId": "getOpenappaBatteries", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string", "enum": [ "bundled", "upload" ] }, "contentHash": { "nullable": true, "type": "string" }, "namespaces": { "type": "array", "items": { "type": "string" } }, "annotators": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string", "enum": [ "catalogs", "organization" ] }, "helpers": { "type": "array", "items": { "type": "string" } }, "credentials": { "type": "array", "items": { "type": "string" } }, "setup": { "nullable": true, "type": "string" }, "installs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "batteryName": { "type": "string" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "target": { "anyOf": [ { "type": "string", "enum": [ "multi-user" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "packageHash": { "nullable": true, "type": "string" }, "lastError": { "nullable": true, "type": "string" }, "credentialBindings": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "batteryName", "catalogId", "enabled", "status", "target", "packageHash", "lastError", "credentialBindings", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "name", "description", "source", "contentHash", "namespaces", "annotators", "scope", "helpers", "credentials", "setup", "installs" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/policy-declarations": { "get": { "operationId": "getOpenappaPolicyDeclarations", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "batteries": { "type": "array", "items": { "type": "object", "properties": { "entry": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "bundled", "upload" ] }, "packageHash": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "scope": { "type": "string", "enum": [ "catalogs", "organization" ] }, "composed": { "type": "boolean" }, "line": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "catalogId": { "nullable": true, "type": "string" } }, "required": [ "target", "catalogId" ], "additionalProperties": false } }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "key": { "nullable": true, "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "policy", "binding" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "readers": { "type": "array", "items": { "type": "string" } } }, "required": [ "variable", "key", "source", "readers" ], "additionalProperties": false } }, "helpers": { "type": "array", "items": { "type": "string" } }, "served": { "nullable": true, "type": "object", "properties": { "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "composed": { "type": "boolean" } }, "required": [ "status", "composed" ], "additionalProperties": false } }, "required": [ "entry", "name", "source", "packageHash", "status", "scope", "composed", "line", "servers", "credentials", "helpers", "served" ], "additionalProperties": false } }, "unusedAliases": { "type": "array", "items": { "type": "object", "properties": { "namespace": { "type": "string" }, "servers": { "type": "array", "items": { "type": "string" } }, "line": { "type": "number" } }, "required": [ "namespace", "servers", "line" ], "additionalProperties": false } }, "repositoryFiles": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ], "additionalProperties": false } }, "rootRevision": { "type": "number" }, "lastError": { "nullable": true, "type": "string" }, "composition": { "type": "object", "properties": { "served": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "current" ] }, "rootRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "composedAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "rootRevision", "composedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "previous" ] }, "rootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "composedAt": { "nullable": true, "type": "string", "format": "date-time" }, "batteries": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "composed": { "type": "boolean" } }, "required": [ "name", "status", "composed" ], "additionalProperties": false } } }, "required": [ "kind", "rootRevision", "composedAt", "batteries" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "root_only" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "refusal": { "nullable": true, "type": "object", "properties": { "message": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "rootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "message", "at", "rootRevision" ], "additionalProperties": false } }, "required": [ "served", "refusal" ], "additionalProperties": false }, "managedInGithub": { "type": "boolean" }, "credentialBindings": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "key": { "type": "string" } }, "required": [ "variable", "key" ], "additionalProperties": false } } }, "required": [ "batteries", "unusedAliases", "repositoryFiles", "rootRevision", "lastError", "composition", "managedInGithub", "credentialBindings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/battery-policy-source": { "get": { "operationId": "getOpenappaBatteryPolicySource", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "entry", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "battery", "repository" ] }, "content": { "type": "string" } }, "required": [ "entry", "name", "kind", "content" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/effective-policy": { "get": { "operationId": "getOpenappaEffectivePolicy", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "content": { "type": "string" }, "contentHash": { "type": "string" }, "rootRevision": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "installFingerprint": { "type": "string" }, "compiledAt": { "type": "string", "format": "date-time" }, "lastError": { "nullable": true, "type": "string" }, "lastErrorAt": { "nullable": true, "type": "string", "format": "date-time" }, "composition": { "type": "object", "properties": { "served": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "current" ] }, "rootRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "composedAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "rootRevision", "composedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "previous" ] }, "rootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "composedAt": { "nullable": true, "type": "string", "format": "date-time" }, "batteries": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "composed": { "type": "boolean" } }, "required": [ "name", "status", "composed" ], "additionalProperties": false } } }, "required": [ "kind", "rootRevision", "composedAt", "batteries" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "root_only" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "refusal": { "nullable": true, "type": "object", "properties": { "message": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "rootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "message", "at", "rootRevision" ], "additionalProperties": false } }, "required": [ "served", "refusal" ], "additionalProperties": false }, "servedRevision": { "nullable": true, "type": "object", "properties": { "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "revision", "publishedAt" ], "additionalProperties": false } }, "required": [ "organizationId", "content", "contentHash", "rootRevision", "installFingerprint", "compiledAt", "lastError", "lastErrorAt", "composition", "servedRevision" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/battery-matches": { "get": { "operationId": "getOpenappaBatteryMatches", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "catalogId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "attach": { "type": "string", "enum": [ "ready", "unsynced", "conflicting" ] }, "matches": { "type": "array", "items": { "type": "object", "properties": { "battery": { "type": "string" }, "evidence": { "type": "string", "enum": [ "host", "image", "name" ] }, "install": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "batteryName": { "type": "string" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "target": { "anyOf": [ { "type": "string", "enum": [ "multi-user" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "packageHash": { "nullable": true, "type": "string" }, "lastError": { "nullable": true, "type": "string" }, "credentialBindings": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "batteryName", "catalogId", "enabled", "status", "target", "packageHash", "lastError", "credentialBindings", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "battery", "evidence", "install" ], "additionalProperties": false } } }, "required": [ "attach", "matches" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/battery-installs": { "post": { "operationId": "createOpenappaBatteryInstall", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batteryName": { "type": "string", "minLength": 1, "maxLength": 100 }, "catalogId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "packageHash": { "default": null, "nullable": true, "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "batteryName" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "bundled", "upload" ] }, "packageHash": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "scope": { "type": "string", "enum": [ "catalogs", "organization" ] }, "composed": { "type": "boolean" }, "line": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "catalogId": { "nullable": true, "type": "string" } }, "required": [ "target", "catalogId" ], "additionalProperties": false } }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "key": { "nullable": true, "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "policy", "binding" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "readers": { "type": "array", "items": { "type": "string" } } }, "required": [ "variable", "key", "source", "readers" ], "additionalProperties": false } }, "helpers": { "type": "array", "items": { "type": "string" } } }, "required": [ "entry", "name", "source", "packageHash", "status", "scope", "composed", "line", "servers", "credentials", "helpers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/battery-installs/{id}": { "get": { "operationId": "getOpenappaBatteryInstall", "tags": [ "OpenAPPA" ], "description": "Get one battery install as the last composition stored it, without recomposing; an install whose battery is no longer available is still returned, with status `unavailable`, though the battery list omits it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "batteryName": { "type": "string" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "target": { "anyOf": [ { "type": "string", "enum": [ "multi-user" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "packageHash": { "nullable": true, "type": "string" }, "lastError": { "nullable": true, "type": "string" }, "credentialBindings": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "batteryName", "catalogId", "enabled", "status", "target", "packageHash", "lastError", "credentialBindings", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] } }, "patch": { "operationId": "updateOpenappaBatteryInstall", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "bundled", "upload" ] }, "packageHash": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "scope": { "type": "string", "enum": [ "catalogs", "organization" ] }, "composed": { "type": "boolean" }, "line": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "catalogId": { "nullable": true, "type": "string" } }, "required": [ "target", "catalogId" ], "additionalProperties": false } }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "key": { "nullable": true, "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "policy", "binding" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "readers": { "type": "array", "items": { "type": "string" } } }, "required": [ "variable", "key", "source", "readers" ], "additionalProperties": false } }, "helpers": { "type": "array", "items": { "type": "string" } } }, "required": [ "entry", "name", "source", "packageHash", "status", "scope", "composed", "line", "servers", "credentials", "helpers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" }, "delete": { "operationId": "deleteOpenappaBatteryInstall", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/battery-includes/{name}": { "delete": { "operationId": "deleteOpenappaBatteryInclude", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/credential-bindings": { "get": { "operationId": "getOpenappaCredentialBindings", "tags": [ "OpenAPPA" ], "description": "List the stored credential bindings; credential values are never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "credentialKey": { "type": "string" }, "hasValue": { "type": "boolean" }, "updatedBy": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "variable", "credentialKey", "hasValue", "updatedBy", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] } } }, "/api/openappa/credential-bindings/{variable}": { "get": { "operationId": "getOpenappaCredentialBinding", "tags": [ "OpenAPPA" ], "description": "Get one stored credential binding; the credential value is never returned.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage", "parameters": [ { "schema": { "type": "string", "pattern": "^APPA_PROVIDER_[A-Z0-9_]+$" }, "in": "path", "name": "variable", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "variable": { "type": "string" }, "credentialKey": { "type": "string" }, "hasValue": { "type": "boolean" }, "updatedBy": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "variable", "credentialKey", "hasValue", "updatedBy", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] } }, "put": { "operationId": "setOpenappaCredentialBinding", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "key" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^APPA_PROVIDER_[A-Z0-9_]+$" }, "in": "path", "name": "variable", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "batteries": { "type": "array", "items": { "type": "object", "properties": { "entry": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "bundled", "upload" ] }, "packageHash": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "scope": { "type": "string", "enum": [ "catalogs", "organization" ] }, "composed": { "type": "boolean" }, "line": { "type": "number" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "catalogId": { "nullable": true, "type": "string" } }, "required": [ "target", "catalogId" ], "additionalProperties": false } }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "key": { "nullable": true, "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "policy", "binding" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "readers": { "type": "array", "items": { "type": "string" } } }, "required": [ "variable", "key", "source", "readers" ], "additionalProperties": false } }, "helpers": { "type": "array", "items": { "type": "string" } }, "served": { "nullable": true, "type": "object", "properties": { "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "composed": { "type": "boolean" } }, "required": [ "status", "composed" ], "additionalProperties": false } }, "required": [ "entry", "name", "source", "packageHash", "status", "scope", "composed", "line", "servers", "credentials", "helpers", "served" ], "additionalProperties": false } }, "unusedAliases": { "type": "array", "items": { "type": "object", "properties": { "namespace": { "type": "string" }, "servers": { "type": "array", "items": { "type": "string" } }, "line": { "type": "number" } }, "required": [ "namespace", "servers", "line" ], "additionalProperties": false } }, "repositoryFiles": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ], "additionalProperties": false } }, "rootRevision": { "type": "number" }, "lastError": { "nullable": true, "type": "string" }, "composition": { "type": "object", "properties": { "served": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "current" ] }, "rootRevision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "composedAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "rootRevision", "composedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "previous" ] }, "rootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "composedAt": { "nullable": true, "type": "string", "format": "date-time" }, "batteries": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, "composed": { "type": "boolean" } }, "required": [ "name", "status", "composed" ], "additionalProperties": false } } }, "required": [ "kind", "rootRevision", "composedAt", "batteries" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "root_only" ] } }, "required": [ "kind" ], "additionalProperties": false } ] }, "refusal": { "nullable": true, "type": "object", "properties": { "message": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "rootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "message", "at", "rootRevision" ], "additionalProperties": false } }, "required": [ "served", "refusal" ], "additionalProperties": false }, "managedInGithub": { "type": "boolean" }, "credentialBindings": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "key": { "type": "string" } }, "required": [ "variable", "key" ], "additionalProperties": false } } }, "required": [ "batteries", "unusedAliases", "repositoryFiles", "rootRevision", "lastError", "composition", "managedInGithub", "credentialBindings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/battery-packages/{name}": { "put": { "operationId": "uploadOpenappaBatteryPackage", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "text": { "type": "string", "maxLength": 1048576 } }, "required": [ "path", "text" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "contentHash": { "type": "string" }, "entry": { "type": "string" }, "namespaces": { "type": "array", "items": { "type": "string" } }, "annotators": { "type": "array", "items": { "type": "string" } }, "helpers": { "type": "array", "items": { "type": "string" } }, "credentials": { "type": "array", "items": { "type": "string" } }, "setup": { "nullable": true, "type": "string" } }, "required": [ "name", "description", "contentHash", "entry", "namespaces", "annotators", "helpers", "credentials", "setup" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/battery-packages/{contentHash}": { "delete": { "operationId": "deleteOpenappaBatteryPackage", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "in": "path", "name": "contentHash", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/coverage/entities": { "get": { "operationId": "getOpenappaCoverageEntities", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "enum": [ "mcp_server" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "entityId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "toolId", "required": false }, { "schema": { "type": "string", "enum": [ "name", "tools" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "mcp_server" ] }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "icon": { "nullable": true, "type": "string" }, "toolCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "governedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fallbackCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rules": { "type": "object", "properties": { "root": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "battery": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notEnforced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "catchAll": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notCovered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "root", "battery", "notEnforced", "catchAll", "notCovered" ], "additionalProperties": false } }, "required": [ "id", "name", "type", "scope", "icon", "toolCount", "governedCount", "fallbackCount", "rules" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/coverage/tools": { "get": { "operationId": "getOpenappaCoverageTools", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "catalogId", "required": false }, { "schema": { "type": "string", "enum": [ "battery", "root", "catchall", "not_covered" ] }, "in": "query", "name": "governedBy", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "battery", "required": false }, { "schema": { "type": "string", "enum": [ "read", "write", "approval" ] }, "in": "query", "name": "kind", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "toolId": { "type": "string" }, "catalogId": { "type": "string" }, "catalogName": { "type": "string" }, "catalogIcon": { "nullable": true, "type": "string" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "fullName": { "type": "string" }, "readOnly": { "nullable": true, "type": "boolean" }, "kind": { "type": "string", "enum": [ "read", "write", "approval", "neutral", "unlisted" ] }, "policySource": { "type": "string", "enum": [ "root", "battery", "catchall", "not_covered" ] }, "rule": { "nullable": true, "type": "object", "properties": { "source": { "type": "string", "enum": [ "root", "battery", "catchall" ] }, "battery": { "nullable": true, "type": "string" }, "batteryEntry": { "nullable": true, "type": "string" }, "batteryStatus": { "nullable": true, "anyOf": [ { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused", "active" ] }, { "type": "string", "enum": [ "pending" ] } ] }, "line": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "selector": { "nullable": true, "type": "string" }, "delta": { "type": "object", "properties": { "trust": { "type": "string" }, "audience": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "forwards": { "type": "object", "properties": { "trust": { "type": "string" }, "audience": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "requires": { "type": "object", "properties": { "trust": { "type": "string" }, "audience": { "type": "array", "items": { "type": "string" } }, "attention": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "annotator": { "nullable": true, "type": "string" }, "enforced": { "type": "boolean" } }, "required": [ "source", "battery", "batteryEntry", "batteryStatus", "line", "name", "selector", "delta", "forwards", "requires", "annotator", "enforced" ], "additionalProperties": false }, "fallbackLine": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unlisted": { "type": "boolean" }, "enforced": { "type": "boolean" } }, "required": [ "toolId", "catalogId", "catalogName", "catalogIcon", "prefix", "name", "fullName", "readOnly", "kind", "policySource", "rule", "fallbackLine", "unlisted", "enforced" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "servers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "icon": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "icon" ], "additionalProperties": false } }, "batteries": { "type": "array", "items": { "type": "string" } } }, "required": [ "data", "pagination", "servers", "batteries" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/coverage/summary": { "get": { "operationId": "getOpenappaCoverageSummary", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "root": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "battery": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notEnforced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "catchAll": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notCovered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tools": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "root", "battery", "notEnforced", "catchAll", "notCovered", "tools" ], "additionalProperties": false }, "batteries": { "type": "object", "properties": { "active": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "tools": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "tools" ], "additionalProperties": false } }, "broken": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "unavailable", "missing_credentials", "naming_conflict", "server_missing", "unrouted", "refused" ] }, { "type": "string", "enum": [ "pending" ] } ] }, "tools": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "status", "tools" ], "additionalProperties": false } }, "available": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "servers": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "servers", "tools" ], "additionalProperties": false } } }, "required": [ "active", "broken", "available" ], "additionalProperties": false }, "composition": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "current", "previous", "root_only" ] }, "servedRootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "refusedRootRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rulesMayDiffer": { "type": "boolean" } }, "required": [ "kind", "servedRootRevision", "refusedRootRevision", "rulesMayDiffer" ], "additionalProperties": false } }, "required": [ "totals", "batteries", "composition" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/guardrail-events": { "get": { "operationId": "getOpenappaGuardrailEvents", "tags": [ "OpenAPPA" ], "description": "What Guardrails recorded in the active organization, newest first: its consults of external services and the yells agents raised, in one timeline. Consults need [`log:read`](/docs/reference/permissions#log:read), which returns the consults of the caller's own sessions; [`log:admin`](/docs/reference/permissions#log:admin) returns every consult in the organization. Yells need [`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read), which returns the yells of the caller's own sessions; [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin) returns every yell in the organization. A kind the caller may not read is left out, and a caller who may read neither is refused. A consult is served as the consults export serves it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`log:read`](/docs/reference/permissions#log:read) or [`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read). Consults are returned with [`log:read`](/docs/reference/permissions#log:read), scoped to the caller's sessions unless the caller also holds [`log:admin`](/docs/reference/permissions#log:admin). Yells are returned with [`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read), scoped to the caller's sessions unless the caller also holds [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin).", "parameters": [ { "schema": { "default": "all", "type": "string", "enum": [ "all", "consult", "yell" ] }, "in": "query", "name": "type", "required": false, "description": "Which records: consults, yells, or both in one timeline" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false, "description": "Case-insensitive substring of a consult's external name or session ID, or of a yell's report" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "from", "required": false, "description": "Recorded on or after this time (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "to", "required": false, "description": "Recorded on or before this time (ISO 8601)" }, { "schema": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "in": "query", "name": "outcome", "required": false, "description": "Only consults with this outcome; leaves yells out" }, { "schema": { "default": "all", "type": "string", "enum": [ "all", "unresolved", "resolved" ] }, "in": "query", "name": "yellStatus", "required": false, "description": "Only yells in this state; leaves consults out unless `all`" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "consult" ] }, "consult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "sessionId": { "nullable": true, "type": "string" }, "callerId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "durationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "role": { "type": "string", "enum": [ "authority", "sanitizer", "annotator", "audience_source", "input", "context_provider" ] }, "externalName": { "type": "string" }, "backend": { "type": "string", "enum": [ "url", "command", "module", "llm", "jev", "claude_code", "hitl", "archestra", "stock" ] }, "request": {}, "outcome": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "answer": { "nullable": true }, "rawResponse": { "nullable": true, "type": "string", "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "httpStatus": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "diagnostics": { "nullable": true, "type": "string", "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "diagnosticsTruncated": { "type": "boolean" }, "root": { "type": "string" }, "trajectory": { "type": "string" }, "callId": { "nullable": true, "type": "string" }, "offerId": { "nullable": true, "type": "string" }, "callDigest": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "sessionId", "callerId", "createdAt", "startedAt", "durationMs", "role", "externalName", "backend", "request", "outcome", "answer", "rawResponse", "httpStatus", "diagnostics", "diagnosticsTruncated", "root", "trajectory", "callId", "offerId", "callDigest" ], "additionalProperties": false } }, "required": [ "type", "consult" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "yell" ] }, "yell": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "callerId": { "type": "string" }, "sessionId": { "type": "string" }, "toolCallId": { "type": "string" }, "message": { "type": "string" }, "withTrajectory": { "type": "boolean" }, "superyell": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "agent", "approval_waived", "block_waived" ] }, "count": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "reportedAt": { "nullable": true, "type": "string", "format": "date-time" }, "reportFailed": { "type": "boolean" }, "resolvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "resolvedBy": { "nullable": true, "type": "string" }, "hasArchive": { "type": "boolean" }, "caller": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "callerApp": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "conversation": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "createdAt" ], "additionalProperties": false }, "trace": { "nullable": true, "type": "object", "properties": { "llmSessionId": { "type": "string" }, "mcpToolCallId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "llmSessionId", "mcpToolCallId" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "callerId", "sessionId", "toolCallId", "message", "withTrajectory", "superyell", "kind", "count", "createdAt", "reportedAt", "reportFailed", "resolvedAt", "resolvedBy", "hasArchive", "caller", "callerApp", "conversation", "trace" ], "additionalProperties": false } }, "required": [ "type", "yell" ], "additionalProperties": false } ] } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `log:read` or `guardrailsYell:read`. Consults are returned with `log:read`, scoped to the caller's sessions unless the caller also holds `log:admin`. Yells are returned with `guardrailsYell:read`, scoped to the caller's sessions unless the caller also holds `guardrailsYell:admin`.", "permissions": [] } } }, "/api/openappa/external-consults": { "get": { "operationId": "getOpenappaExternalConsults", "tags": [ "OpenAPPA" ], "description": "Export the external consults Guardrails recorded in the active organization, newest first. [`log:read`](/docs/reference/permissions#log:read) returns the consults of the caller's own sessions. [`log:admin`](/docs/reference/permissions#log:admin) returns every consult in the organization. An audience source's consult names people, so its `request`, `answer`, `rawResponse` and `diagnostics` are null for a caller without [`member:read`](/docs/reference/permissions#member:read). Byte fields are base64.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "externalName", "required": false }, { "schema": { "type": "string", "enum": [ "authority", "sanitizer", "annotator", "audience_source", "input", "context_provider" ] }, "in": "query", "name": "role", "required": false }, { "schema": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "in": "query", "name": "outcome", "required": false }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "from", "required": false, "description": "Recorded on or after this time (ISO 8601)" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "to", "required": false, "description": "Recorded on or before this time (ISO 8601)" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "root", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "sessionId", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "llmSessionId", "required": false, "description": "An LLM session ID, as on the LLM logs page: consults from every trajectory of that session, sub-agents included" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "search", "required": false, "description": "Case-insensitive substring of the external's name or the session ID" }, { "schema": { "default": "json", "type": "string", "enum": [ "json", "jsonl" ] }, "in": "query", "name": "format", "required": false, "description": "`jsonl` streams up to 10000 rows as application/x-ndjson, one consult per line, ignoring `limit`" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "sessionId": { "nullable": true, "type": "string" }, "callerId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "durationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "role": { "type": "string", "enum": [ "authority", "sanitizer", "annotator", "audience_source", "input", "context_provider" ] }, "externalName": { "type": "string" }, "backend": { "type": "string", "enum": [ "url", "command", "module", "llm", "jev", "claude_code", "hitl", "archestra", "stock" ] }, "request": {}, "outcome": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "answer": { "nullable": true }, "rawResponse": { "nullable": true, "type": "string", "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "httpStatus": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "diagnostics": { "nullable": true, "type": "string", "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "diagnosticsTruncated": { "type": "boolean" }, "root": { "type": "string" }, "trajectory": { "type": "string" }, "callId": { "nullable": true, "type": "string" }, "offerId": { "nullable": true, "type": "string" }, "callDigest": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "sessionId", "callerId", "createdAt", "startedAt", "durationMs", "role", "externalName", "backend", "request", "outcome", "answer", "rawResponse", "httpStatus", "diagnostics", "diagnosticsTruncated", "root", "trajectory", "callId", "offerId", "callDigest" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/openappa/external-consults/{id}": { "get": { "operationId": "getOpenappaExternalConsult", "tags": [ "OpenAPPA" ], "description": "One external consult Guardrails recorded, with where it happened: `llmSessionId` is the LLM session it belongs to and `mcpToolCallId` the logged tool call it was raised for, each null when not logged. Access is as for the list.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "consult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "sessionId": { "nullable": true, "type": "string" }, "callerId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "durationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "role": { "type": "string", "enum": [ "authority", "sanitizer", "annotator", "audience_source", "input", "context_provider" ] }, "externalName": { "type": "string" }, "backend": { "type": "string", "enum": [ "url", "command", "module", "llm", "jev", "claude_code", "hitl", "archestra", "stock" ] }, "request": {}, "outcome": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "answer": { "nullable": true }, "rawResponse": { "nullable": true, "type": "string", "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "httpStatus": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "diagnostics": { "nullable": true, "type": "string", "format": "base64", "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$" }, "diagnosticsTruncated": { "type": "boolean" }, "root": { "type": "string" }, "trajectory": { "type": "string" }, "callId": { "nullable": true, "type": "string" }, "offerId": { "nullable": true, "type": "string" }, "callDigest": { "nullable": true, "type": "string" } }, "required": [ "id", "organizationId", "sessionId", "callerId", "createdAt", "startedAt", "durationMs", "role", "externalName", "backend", "request", "outcome", "answer", "rawResponse", "httpStatus", "diagnostics", "diagnosticsTruncated", "root", "trajectory", "callId", "offerId", "callDigest" ], "additionalProperties": false }, "llmSessionId": { "nullable": true, "type": "string" }, "mcpToolCallId": { "nullable": true, "type": "string" } }, "required": [ "consult", "llmSessionId", "mcpToolCallId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/openappa/github-sync": { "get": { "operationId": "getAppaGithubSync", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "source": { "nullable": true, "type": "object", "properties": { "organizationId": { "type": "string" }, "repo": { "nullable": true, "type": "string" }, "ref": { "nullable": true, "type": "string" }, "path": { "nullable": true, "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceCommit": { "nullable": true, "type": "string" }, "setupPullRequestNumber": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "selfService": { "type": "boolean" }, "selfServiceDirectory": { "type": "string" }, "selfServiceAutoMerge": { "type": "boolean" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" } }, "required": [ "organizationId", "repo", "ref", "path", "interval", "githubPatId", "githubAppConfigId", "gitlabTokenId", "revision", "sourceCommit", "setupPullRequestNumber", "selfService", "selfServiceDirectory", "selfServiceAutoMerge", "lastSyncedAt", "lastSyncError" ], "additionalProperties": false }, "selfService": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "directory": { "type": "string" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false }, "leftoverRule": { "type": "object", "properties": { "checkName": { "type": "string" }, "url": { "nullable": true, "type": "string" } }, "required": [ "checkName", "url" ], "additionalProperties": false }, "autoMerge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false } }, "required": [ "enabled", "setting" ], "additionalProperties": false } }, "required": [ "enabled", "setting", "directory", "autoMerge" ], "additionalProperties": false }, "hasPolicy": { "type": "boolean" }, "validationDirectory": { "type": "string" }, "githubWebUrl": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "templateFiles": { "type": "object", "properties": { "templateCommit": { "type": "string" }, "state": { "type": "string", "enum": [ "current", "pull_open", "needs_permission", "not_applicable", "unavailable" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "withheld": { "type": "array", "items": { "type": "string" } }, "pull": { "type": "object", "properties": { "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" } }, "required": [ "number", "url" ], "additionalProperties": false }, "detail": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "templateCommit", "state", "paths", "checkedAt" ], "additionalProperties": false }, "check": { "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "posted", "refused", "none" ] }, "detail": { "type": "string" } }, "required": [ "name", "state" ], "additionalProperties": false } }, "required": [ "enabled", "source", "selfService", "hasPolicy", "validationDirectory", "githubWebUrl", "provider" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels" }, "put": { "operationId": "configureAppaGithubSync", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string", "maxLength": 400, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*(\\/[a-zA-Z0-9_.-]+)+$" }, "ref": { "default": null, "nullable": true, "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\p{Cc}\\s~^:?*[\\\\]+$" }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "interval": { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] }, "validationDirectory": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" } ] }, "githubPatId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubAppConfigId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "default": null, "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "selfService": { "default": false, "type": "boolean" }, "selfServiceDirectory": { "default": "mcp", "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^(?!batteries(?:\\/|$))[A-Za-z0-9_-][A-Za-z0-9_.-]*(?:\\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$" }, "selfServiceAutoMerge": { "default": false, "type": "boolean" } }, "required": [ "repo", "path", "interval" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "source": { "nullable": true, "type": "object", "properties": { "organizationId": { "type": "string" }, "repo": { "nullable": true, "type": "string" }, "ref": { "nullable": true, "type": "string" }, "path": { "nullable": true, "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceCommit": { "nullable": true, "type": "string" }, "setupPullRequestNumber": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "selfService": { "type": "boolean" }, "selfServiceDirectory": { "type": "string" }, "selfServiceAutoMerge": { "type": "boolean" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" } }, "required": [ "organizationId", "repo", "ref", "path", "interval", "githubPatId", "githubAppConfigId", "gitlabTokenId", "revision", "sourceCommit", "setupPullRequestNumber", "selfService", "selfServiceDirectory", "selfServiceAutoMerge", "lastSyncedAt", "lastSyncError" ], "additionalProperties": false }, "selfService": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "directory": { "type": "string" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false }, "leftoverRule": { "type": "object", "properties": { "checkName": { "type": "string" }, "url": { "nullable": true, "type": "string" } }, "required": [ "checkName", "url" ], "additionalProperties": false }, "autoMerge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false } }, "required": [ "enabled", "setting" ], "additionalProperties": false } }, "required": [ "enabled", "setting", "directory", "autoMerge" ], "additionalProperties": false }, "hasPolicy": { "type": "boolean" }, "validationDirectory": { "type": "string" }, "githubWebUrl": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "templateFiles": { "type": "object", "properties": { "templateCommit": { "type": "string" }, "state": { "type": "string", "enum": [ "current", "pull_open", "needs_permission", "not_applicable", "unavailable" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "withheld": { "type": "array", "items": { "type": "string" } }, "pull": { "type": "object", "properties": { "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" } }, "required": [ "number", "url" ], "additionalProperties": false }, "detail": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "templateCommit", "state", "paths", "checkedAt" ], "additionalProperties": false }, "check": { "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "posted", "refused", "none" ] }, "detail": { "type": "string" } }, "required": [ "name", "state" ], "additionalProperties": false } }, "required": [ "enabled", "source", "selfService", "hasPolicy", "validationDirectory", "githubWebUrl", "provider" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" }, "patch": { "operationId": "updateAppaGithubSync", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "sync" ] } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "disconnect" ] } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "schedule" ] }, "interval": { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] } }, "required": [ "action", "interval" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "self_service" ] }, "enabled": { "type": "boolean" }, "directory": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^(?!batteries(?:\\/|$))[A-Za-z0-9_-][A-Za-z0-9_.-]*(?:\\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$" } }, "required": [ "action", "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "self_service_auto_merge" ] }, "enabled": { "type": "boolean" } }, "required": [ "action", "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "include_servers" ] } }, "required": [ "action" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "source": { "nullable": true, "type": "object", "properties": { "organizationId": { "type": "string" }, "repo": { "nullable": true, "type": "string" }, "ref": { "nullable": true, "type": "string" }, "path": { "nullable": true, "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceCommit": { "nullable": true, "type": "string" }, "setupPullRequestNumber": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "selfService": { "type": "boolean" }, "selfServiceDirectory": { "type": "string" }, "selfServiceAutoMerge": { "type": "boolean" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" } }, "required": [ "organizationId", "repo", "ref", "path", "interval", "githubPatId", "githubAppConfigId", "gitlabTokenId", "revision", "sourceCommit", "setupPullRequestNumber", "selfService", "selfServiceDirectory", "selfServiceAutoMerge", "lastSyncedAt", "lastSyncError" ], "additionalProperties": false }, "selfService": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "directory": { "type": "string" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false }, "leftoverRule": { "type": "object", "properties": { "checkName": { "type": "string" }, "url": { "nullable": true, "type": "string" } }, "required": [ "checkName", "url" ], "additionalProperties": false }, "autoMerge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false } }, "required": [ "enabled", "setting" ], "additionalProperties": false } }, "required": [ "enabled", "setting", "directory", "autoMerge" ], "additionalProperties": false }, "hasPolicy": { "type": "boolean" }, "validationDirectory": { "type": "string" }, "githubWebUrl": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "templateFiles": { "type": "object", "properties": { "templateCommit": { "type": "string" }, "state": { "type": "string", "enum": [ "current", "pull_open", "needs_permission", "not_applicable", "unavailable" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "withheld": { "type": "array", "items": { "type": "string" } }, "pull": { "type": "object", "properties": { "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" } }, "required": [ "number", "url" ], "additionalProperties": false }, "detail": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "templateCommit", "state", "paths", "checkedAt" ], "additionalProperties": false }, "check": { "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "posted", "refused", "none" ] }, "detail": { "type": "string" } }, "required": [ "name", "state" ], "additionalProperties": false } }, "required": [ "enabled", "source", "selfService", "hasPolicy", "validationDirectory", "githubWebUrl", "provider" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/openappa/github-sync/protection": { "get": { "operationId": "getAppaRepositoryProtection", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "fresh", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "checkName": { "type": "string" }, "app": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "nullable": true, "type": "string" }, "settingsUrl": { "type": "string" }, "installationUrl": { "nullable": true, "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "contents", "pull_requests", "checks", "workflows" ] }, "granted": { "type": "boolean" } }, "required": [ "name", "granted" ], "additionalProperties": false } } }, "required": [ "name", "url", "settingsUrl", "installationUrl", "permissions" ], "additionalProperties": false }, "branchRules": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "incomplete", "missing", "needs_permission", "unavailable", "error" ] }, "url": { "type": "string" }, "detail": { "type": "string" }, "checkRule": { "type": "string", "enum": [ "unposted" ] }, "settingsUrl": { "type": "string" }, "ruleset": { "type": "object", "properties": { "name": { "type": "string" }, "target": { "type": "string", "enum": [ "branch" ] }, "source_type": { "type": "string", "enum": [ "Repository" ] }, "source": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "active" ] }, "conditions": { "type": "object", "properties": { "ref_name": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "required": [ "include", "exclude" ], "additionalProperties": false } }, "required": [ "ref_name" ], "additionalProperties": false }, "bypass_actors": { "type": "array", "items": {} }, "rules": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "parameters": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": false } } }, "required": [ "name", "target", "enforcement", "conditions", "bypass_actors", "rules" ], "additionalProperties": false } }, "required": [ "state" ], "additionalProperties": false }, "include": { "type": "object", "properties": { "folder": { "type": "string" }, "state": { "type": "string", "enum": [ "included", "pull_open", "missing", "unknown" ] }, "pull": { "type": "object", "properties": { "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" } }, "required": [ "number", "url" ], "additionalProperties": false } }, "required": [ "folder", "state" ], "additionalProperties": false } }, "required": [ "checkName", "branchRules", "include" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels" } }, "/api/openappa/github-sync/app-grants": { "get": { "operationId": "getAppaGithubAppGrants", "tags": [ "OpenAPPA" ], "description": "The GitHub App's permissions against what self-service needs, with the pages that grant them\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "url": { "nullable": true, "type": "string" }, "settingsUrl": { "type": "string" }, "installationUrl": { "nullable": true, "type": "string" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "contents", "pull_requests", "checks", "workflows" ] }, "granted": { "type": "boolean" } }, "required": [ "name", "granted" ], "additionalProperties": false } } }, "required": [ "name", "url", "settingsUrl", "installationUrl", "permissions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/openappa/github-sync/self-service": { "get": { "operationId": "getAppaSelfService", "tags": [ "OpenAPPA" ], "description": "Whether MCP server editors change their servers' Guardrails rules themselves, through pull requests on the policy repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/openappa/server-rules/files": { "get": { "operationId": "getOpenappaServerRulesFiles", "tags": [ "OpenAPPA" ], "description": "The MCP servers' Guardrails rules files the caller may open: those of servers they may open in the MCP registry\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "servers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "canEdit": { "type": "boolean" } }, "required": [ "path", "servers", "canEdit" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/openappa/server-rules/source": { "get": { "operationId": "getOpenappaServerRulesSource", "tags": [ "OpenAPPA" ], "description": "One MCP server's Guardrails rules file, for a caller who may open that server in the MCP registry\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "entry", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "battery", "repository" ] }, "content": { "type": "string" } }, "required": [ "entry", "name", "kind", "content" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/openappa/github-sync/repository": { "post": { "operationId": "createAppaGithubRepository", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "string", "maxLength": 255, "pattern": "^([a-zA-Z0-9][a-zA-Z0-9_.-]*(\\/[a-zA-Z0-9_.-]+)*)?$" }, "name": { "type": "string", "maxLength": 100, "pattern": "^[a-zA-Z0-9_.-]+$" }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "interval": { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] }, "existing": { "type": "boolean" }, "ref": { "default": null, "nullable": true, "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\p{Cc}\\s~^:?*[\\\\]+$" }, "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "validationDirectory": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "replace": { "type": "boolean" }, "selfService": { "type": "boolean" }, "selfServiceDirectory": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^(?!batteries(?:\\/|$))[A-Za-z0-9_-][A-Za-z0-9_.-]*(?:\\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$" }, "selfServiceAutoMerge": { "type": "boolean" } }, "required": [ "owner", "name", "interval" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "source": { "nullable": true, "type": "object", "properties": { "organizationId": { "type": "string" }, "repo": { "nullable": true, "type": "string" }, "ref": { "nullable": true, "type": "string" }, "path": { "nullable": true, "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceCommit": { "nullable": true, "type": "string" }, "setupPullRequestNumber": { "nullable": true, "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "selfService": { "type": "boolean" }, "selfServiceDirectory": { "type": "string" }, "selfServiceAutoMerge": { "type": "boolean" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" } }, "required": [ "organizationId", "repo", "ref", "path", "interval", "githubPatId", "githubAppConfigId", "gitlabTokenId", "revision", "sourceCommit", "setupPullRequestNumber", "selfService", "selfServiceDirectory", "selfServiceAutoMerge", "lastSyncedAt", "lastSyncError" ], "additionalProperties": false }, "selfService": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "directory": { "type": "string" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false }, "leftoverRule": { "type": "object", "properties": { "checkName": { "type": "string" }, "url": { "nullable": true, "type": "string" } }, "required": [ "checkName", "url" ], "additionalProperties": false }, "autoMerge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "setting": { "type": "boolean" }, "environment": { "type": "object", "properties": { "variable": { "type": "string" }, "value": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "variable", "value" ], "additionalProperties": false } }, "required": [ "enabled", "setting" ], "additionalProperties": false } }, "required": [ "enabled", "setting", "directory", "autoMerge" ], "additionalProperties": false }, "hasPolicy": { "type": "boolean" }, "validationDirectory": { "type": "string" }, "githubWebUrl": { "type": "string" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "templateFiles": { "type": "object", "properties": { "templateCommit": { "type": "string" }, "state": { "type": "string", "enum": [ "current", "pull_open", "needs_permission", "not_applicable", "unavailable" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "withheld": { "type": "array", "items": { "type": "string" } }, "pull": { "type": "object", "properties": { "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" } }, "required": [ "number", "url" ], "additionalProperties": false }, "detail": { "type": "string" }, "checkedAt": { "type": "string" } }, "required": [ "templateCommit", "state", "paths", "checkedAt" ], "additionalProperties": false }, "check": { "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "posted", "refused", "none" ] }, "detail": { "type": "string" } }, "required": [ "name", "state" ], "additionalProperties": false } }, "required": [ "enabled", "source", "selfService", "hasPolicy", "validationDirectory", "githubWebUrl", "provider" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications" } }, "/api/openappa/github-app/manifest": { "post": { "operationId": "startAppaGithubApp", "tags": [ "OpenAPPA" ], "description": "Start registering the OpenAPPA GitHub App, from a manifest, on the account that owns the policy repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "githubUrl": { "type": "string", "maxLength": 500, "format": "uri" }, "owner": { "type": "string", "maxLength": 39, "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9]))*$" } }, "required": [ "githubUrl", "owner" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "manifest": { "type": "string" } }, "required": [ "url", "manifest" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/openappa/github-app/manifest/complete": { "post": { "operationId": "completeAppaGithubApp", "tags": [ "OpenAPPA" ], "description": "Exchange GitHub's one-time code for the new App; it is stored once installed\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 512 }, "state": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "code", "state" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "account": { "type": "string" }, "appId": { "type": "string" }, "accountUrl": { "type": "string" }, "htmlUrl": { "type": "string" }, "installUrl": { "type": "string" }, "settingsUrl": { "type": "string" } }, "required": [ "name", "slug", "account", "appId", "accountUrl", "htmlUrl", "installUrl", "settingsUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/openappa/github-app/pending": { "get": { "operationId": "getPendingAppaGithubApp", "tags": [ "OpenAPPA" ], "description": "The GitHub App created during setup that is not installed yet\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "account": { "type": "string" }, "appId": { "type": "string" }, "accountUrl": { "type": "string" }, "htmlUrl": { "type": "string" }, "installUrl": { "type": "string" }, "settingsUrl": { "type": "string" } }, "required": [ "name", "slug", "account", "appId", "accountUrl", "htmlUrl", "installUrl", "settingsUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "delete": { "operationId": "discardAppaGithubApp", "tags": [ "OpenAPPA" ], "description": "Forget the GitHub App created during setup so setup can start over\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/openappa/github-app/install": { "post": { "operationId": "installAppaGithubApp", "tags": [ "OpenAPPA" ], "description": "Store the new GitHub App as an organization credential once it is installed\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "installed" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "account": { "type": "string" } }, "required": [ "status", "id", "name", "account" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/openappa/github-app/repository": { "get": { "operationId": "getAppaGithubRepositoryStatus", "tags": [ "OpenAPPA" ], "description": "Whether a policy repository already exists, as far as the organization's GitHub Apps can see\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "credentialId", "required": true }, { "schema": { "type": "string", "maxLength": 400, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*(?:\\/[a-zA-Z0-9_.-]+)+$" }, "in": "query", "name": "repo", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "ref", "required": false }, { "schema": { "type": "string", "maxLength": 500, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*\\.toml$" }, "in": "query", "name": "path", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "in": "query", "name": "validationDirectory", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "template", "empty", "policy", "other", "unreachable", "app_error" ] }, "validations": { "nullable": true, "type": "boolean" } }, "required": [ "status", "validations" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/openappa/github-app/accounts": { "get": { "operationId": "getAppaGithubAppAccounts", "tags": [ "OpenAPPA" ], "description": "The GitHub account each organization GitHub App is installed on\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "account": { "nullable": true, "type": "string" }, "url": { "nullable": true, "type": "string" } }, "required": [ "id", "account", "url" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } } }, "/api/openappa/github-app/repositories": { "get": { "operationId": "getAppaGithubAppRepositories", "tags": [ "OpenAPPA" ], "description": "The repositories an organization GitHub App can reach, recent template copies first\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "credentialId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repositories": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string" }, "private": { "type": "boolean" }, "description": { "nullable": true, "type": "string" }, "template": { "type": "boolean" } }, "required": [ "fullName", "private", "description", "template" ], "additionalProperties": false } }, "manageUrl": { "nullable": true, "type": "string" } }, "required": [ "repositories", "manageUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/openappa/helpers/{installId}/{externalName}": { "post": { "operationId": "consultOpenappaBatteryHelper", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "installId", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" }, "in": "path", "name": "externalName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/openappa/label-changes": { "get": { "operationId": "getOpenappaLabelChanges", "tags": [ "OpenAPPA" ], "description": "The trust and audience label of an LLM session over time, oldest first: a `session_start` baseline, then one row per change, with the event that moved it and the rule the current policy applies to the tool. Viewers who may not read everyone's consults see only their own sessions.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`log:read`](/docs/reference/permissions#log:read): View your own LLM proxy, MCP tool call, and Guardrails consult logs in the active organization", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "llmSessionId", "required": true, "description": "An LLM session ID, as on the LLM logs page" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "root": { "type": "string" }, "sessionId": { "type": "string" }, "callerId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "event": { "type": "string", "enum": [ "session_start", "tool_call", "tool_result", "remedy", "child_return", "other" ] }, "callId": { "nullable": true, "type": "string" }, "tool": { "nullable": true, "description": "The full tool name, from the record or the logged tool call", "type": "string" }, "trustBefore": { "type": "string" }, "audienceBefore": { "type": "string" }, "trustAfter": { "type": "string" }, "audienceAfter": { "type": "string" }, "policyRevision": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rule": { "nullable": true, "description": "The rule the current policy applies to the tool (the first that names it, else the catch-all). The engine does not record which rule matched a call.", "type": "object", "properties": { "source": { "type": "string", "enum": [ "root", "battery", "catchall" ] }, "battery": { "nullable": true, "type": "string" }, "batteryEntry": { "nullable": true, "type": "string" }, "line": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "nullable": true, "description": "The rule's TOML block", "type": "string" } }, "required": [ "source", "battery", "batteryEntry", "line", "text" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "root", "sessionId", "callerId", "createdAt", "event", "callId", "tool", "trustBefore", "audienceBefore", "trustAfter", "audienceAfter", "policyRevision", "rule" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "log:read" ] } } }, "/api/openappa/policy-tests/inspect": { "post": { "operationId": "inspectOpenAppaPolicyTests", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "content": { "type": "string", "maxLength": 65536 } }, "required": [ "path", "content" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "tools": { "type": "array", "items": { "type": "string" } }, "assertionCount": { "nullable": true, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "error": { "nullable": true, "type": "string" } }, "required": [ "path", "tools", "assertionCount", "error" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/policy-tests": { "get": { "operationId": "getOpenAppaPolicyTests", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "local", "github" ] }, "files": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "content": { "type": "string", "maxLength": 65536 } }, "required": [ "path", "content" ], "additionalProperties": false } }, "version": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "directory": { "type": "string" }, "activeDirectory": { "type": "string" }, "error": { "nullable": true, "type": "string" } }, "required": [ "source", "files", "version", "sourceCommit", "directory", "activeDirectory", "error" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" }, "put": { "operationId": "updateOpenAppaPolicyTests", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "content": { "type": "string", "maxLength": 65536 } }, "required": [ "path", "content" ], "additionalProperties": false } }, "expectedVersion": { "type": "string" } }, "required": [ "files", "expectedVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "local", "github" ] }, "files": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "content": { "type": "string", "maxLength": 65536 } }, "required": [ "path", "content" ], "additionalProperties": false } }, "version": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "directory": { "type": "string" }, "activeDirectory": { "type": "string" }, "error": { "nullable": true, "type": "string" } }, "required": [ "source", "files", "version", "sourceCommit", "directory", "activeDirectory", "error" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/policy-tests/run": { "post": { "operationId": "runOpenAppaPolicyTests", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "content": { "type": "string", "maxLength": 65536 } }, "required": [ "path", "content" ], "additionalProperties": false } }, "sourceVersion": { "type": "string" }, "directory": { "default": "traces", "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "partial": { "type": "boolean" }, "progressToken": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "files", "sourceVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdBy": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "trigger": { "type": "string", "enum": [ "manual", "github_sync", "policy_change" ] }, "partial": { "type": "boolean" }, "executionError": { "type": "string" }, "source": { "type": "string", "enum": [ "local", "github" ] }, "sourceVersion": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "definitionHash": { "type": "string" }, "policyRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "policyHash": { "type": "string" }, "effectivePolicyHash": { "type": "string" }, "engineVersion": { "type": "string" }, "draft": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "assertionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "passed", "failed", "cannot_run" ] }, "error": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tool": { "type": "string" }, "expected": { "type": "string" }, "actual": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "passed", "failed", "cannot_run" ] }, "error": { "nullable": true, "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "line", "tool", "expected", "actual", "status" ], "additionalProperties": false } } }, "required": [ "path", "assertionCount", "status", "contentHash", "steps" ], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "errors", "warnings" ], "additionalProperties": false } }, "required": [ "id", "createdBy", "createdAt", "source", "sourceVersion", "sourceCommit", "definitionHash", "policyRevision", "policyHash", "effectivePolicyHash", "engineVersion", "draft", "files", "validation" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/policy-tests/runs": { "get": { "operationId": "getOpenAppaPolicyTestRuns", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdBy": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "trigger": { "type": "string", "enum": [ "manual", "github_sync", "policy_change" ] }, "partial": { "type": "boolean" }, "executionError": { "type": "string" }, "source": { "type": "string", "enum": [ "local", "github" ] }, "sourceVersion": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "definitionHash": { "type": "string" }, "policyRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "policyHash": { "type": "string" }, "effectivePolicyHash": { "type": "string" }, "engineVersion": { "type": "string" }, "draft": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "assertionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "passed", "failed", "cannot_run" ] }, "error": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tool": { "type": "string" }, "expected": { "type": "string" }, "actual": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "passed", "failed", "cannot_run" ] }, "error": { "nullable": true, "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "line", "tool", "expected", "actual", "status" ], "additionalProperties": false } } }, "required": [ "path", "assertionCount", "status", "contentHash", "steps" ], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "errors", "warnings" ], "additionalProperties": false } }, "required": [ "id", "createdBy", "createdAt", "source", "sourceVersion", "sourceCommit", "definitionHash", "policyRevision", "policyHash", "effectivePolicyHash", "engineVersion", "draft", "files", "validation" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage" } }, "/api/openappa/policy-tests/preview": { "post": { "operationId": "previewOpenAppaPolicyTest", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" }, "content": { "type": "string", "maxLength": 65536 } }, "required": [ "path", "content" ], "additionalProperties": false } }, "sourceVersion": { "type": "string" }, "directory": { "default": "traces", "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^[a-zA-Z0-9_.-]+(?:\\/[a-zA-Z0-9_.-]+)*$" } }, "required": [ "files", "sourceVersion" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "manual", "github_sync", "policy_change" ] }, "partial": { "type": "boolean" }, "executionError": { "type": "string" }, "source": { "type": "string", "enum": [ "local", "github" ] }, "sourceVersion": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "definitionHash": { "type": "string" }, "policyRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "policyHash": { "type": "string" }, "effectivePolicyHash": { "type": "string" }, "engineVersion": { "type": "string" }, "draft": { "type": "boolean" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "assertionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "passed", "failed", "cannot_run" ] }, "error": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "steps": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tool": { "type": "string" }, "expected": { "type": "string" }, "actual": { "nullable": true, "type": "string" }, "status": { "type": "string", "enum": [ "passed", "failed", "cannot_run" ] }, "error": { "nullable": true, "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "line", "tool", "expected", "actual", "status" ], "additionalProperties": false } } }, "required": [ "path", "assertionCount", "status", "contentHash", "steps" ], "additionalProperties": false } }, "validation": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "errors", "warnings" ], "additionalProperties": false } }, "required": [ "source", "sourceVersion", "sourceCommit", "definitionHash", "policyRevision", "policyHash", "effectivePolicyHash", "engineVersion", "draft", "files", "validation" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:update" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:update`](/docs/reference/permissions#guardrailsPolicy:update): Validate and edit Guardrails policy and manage batteries" } }, "/api/openappa/remedies": { "get": { "operationId": "getOpenappaRemedies", "tags": [ "OpenAPPA" ], "description": "The authorities and sanitizers the policy and its included batteries declare, who runs each, what it may lift, and which kinds of block the rules can cause that no wired remedy lifts. `lastConsult` is filled only for a caller with [`log:admin`](/docs/reference/permissions#log:admin).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "source": { "type": "object", "properties": { "entry": { "nullable": true, "type": "string" }, "battery": { "nullable": true, "type": "string" }, "line": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "entry", "battery", "line" ], "additionalProperties": false }, "implementation": { "nullable": true, "type": "object", "properties": { "kind": { "type": "string", "enum": [ "hitl", "approve", "llm", "claude_code", "builtin", "module", "url", "command" ] }, "detail": { "nullable": true, "type": "string" } }, "required": [ "kind", "detail" ], "additionalProperties": false }, "tags": { "type": "array", "items": { "type": "string" } }, "lastConsult": { "nullable": true, "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "outcome", "at" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "authority" ] }, "permits": { "type": "object", "properties": { "attention": { "type": "array", "items": { "type": "string" } }, "audienceMissing": { "type": "array", "items": { "type": "string" } }, "trustBelow": { "nullable": true, "type": "string" }, "effectsContaining": { "type": "array", "items": { "type": "string" } } }, "required": [ "attention", "audienceMissing", "trustBelow", "effectsContaining" ], "additionalProperties": false } }, "required": [ "name", "source", "implementation", "tags", "lastConsult", "kind", "permits" ], "additionalProperties": false } }, "sanitizers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "source": { "type": "object", "properties": { "entry": { "nullable": true, "type": "string" }, "battery": { "nullable": true, "type": "string" }, "line": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "entry", "battery", "line" ], "additionalProperties": false }, "implementation": { "nullable": true, "type": "object", "properties": { "kind": { "type": "string", "enum": [ "hitl", "approve", "llm", "claude_code", "builtin", "module", "url", "command" ] }, "detail": { "nullable": true, "type": "string" } }, "required": [ "kind", "detail" ], "additionalProperties": false }, "tags": { "type": "array", "items": { "type": "string" } }, "lastConsult": { "nullable": true, "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "outcome", "at" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "sanitizer" ] }, "on": { "type": "array", "items": { "type": "string", "enum": [ "tool_output", "tool_input" ] } }, "permits": { "nullable": true, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audience" ] }, "from": { "type": "array", "items": { "type": "string" } }, "to": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "from", "to" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "trust" ] }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "kind", "from", "to" ], "additionalProperties": false } ] } }, "required": [ "name", "source", "implementation", "tags", "lastConsult", "kind", "on", "permits" ], "additionalProperties": false } }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "trust", "audience", "effects", "approvals" ] }, "level": { "nullable": true, "type": "string" }, "approvers": { "type": "array", "items": { "type": "string" } }, "cleaners": { "type": "array", "items": { "type": "string" } }, "unservedMarks": { "type": "array", "items": { "type": "string" } }, "covered": { "type": "boolean" } }, "required": [ "kind", "level", "approvers", "cleaners", "unservedMarks", "covered" ], "additionalProperties": false } } }, "required": [ "authorities", "sanitizers", "blocks" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] } } }, "/api/openappa/remedies/activity": { "get": { "operationId": "getOpenappaRemediesActivity", "tags": [ "OpenAPPA" ], "description": "Tool calls the runtime denied on each of the last seven days, by how each ended: approved by an authority, cleaned by a sanitizer, or blocked when neither lifted it. Days are calendar days in `timeZone`.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage", "parameters": [ { "schema": { "default": "UTC", "type": "string", "maxLength": 64 }, "in": "query", "name": "timeZone", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "blocked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "approved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cleaned": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "date", "blocked", "approved", "cleaned" ], "additionalProperties": false } } }, "required": [ "timeZone", "days" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] } } }, "/api/openappa/trust-audience": { "get": { "operationId": "getOpenappaTrustAudience", "tags": [ "OpenAPPA" ], "description": "The trust levels and audiences the policy works with, the audience sources included batteries declare, and the rules naming each audience. `lastConsult` is filled only for a caller with [`log:admin`](/docs/reference/permissions#log:admin).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsPolicy:read`](/docs/reference/permissions#guardrailsPolicy:read): View Guardrails policy, batteries, and coverage", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "trust": { "type": "array", "items": { "type": "string" } }, "audiences": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "builtin" ] } }, "required": [ "name", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "mapped" ] }, "mappingLine": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "from": { "type": "array", "items": { "type": "object", "properties": { "entry": { "nullable": true, "type": "string" }, "line": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source": { "type": "string" }, "selector": { "type": "string" }, "declaredBy": { "nullable": true, "type": "object", "properties": { "battery": { "type": "string" }, "runBy": { "type": "string", "enum": [ "archestra", "helper" ] }, "lastConsult": { "nullable": true, "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "answered", "unregistered", "unreachable", "dismissed", "non_success", "timeout", "transport", "malformed", "oversized", "unsupported_version", "module_error", "module_panicked" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "outcome", "at" ], "additionalProperties": false } }, "required": [ "battery", "runBy", "lastConsult" ], "additionalProperties": false } }, "required": [ "entry", "line", "source", "selector", "declaredBy" ], "additionalProperties": false } }, "within": { "nullable": true, "type": "string" } }, "required": [ "name", "kind", "mappingLine", "from", "within" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "unmapped" ] } }, "required": [ "name", "kind" ], "additionalProperties": false } ] } } }, "required": [ "trust", "audiences" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "guardrailsPolicy:read" ] } } }, "/api/openappa/yells": { "get": { "operationId": "getOpenAppaYells", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "search", "required": false }, { "schema": { "default": "unresolved", "type": "string", "enum": [ "unresolved", "resolved", "all" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "in": "query", "name": "llmSessionId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "callerId": { "type": "string" }, "sessionId": { "type": "string" }, "toolCallId": { "type": "string" }, "message": { "type": "string" }, "withTrajectory": { "type": "boolean" }, "superyell": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "agent", "approval_waived", "block_waived" ] }, "count": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "reportedAt": { "nullable": true, "type": "string", "format": "date-time" }, "reportFailed": { "type": "boolean" }, "resolvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "resolvedBy": { "nullable": true, "type": "string" }, "hasArchive": { "type": "boolean" }, "caller": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "callerApp": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "conversation": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "createdAt" ], "additionalProperties": false }, "trace": { "nullable": true, "type": "object", "properties": { "llmSessionId": { "type": "string" }, "mcpToolCallId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "llmSessionId", "mcpToolCallId" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "callerId", "sessionId", "toolCallId", "message", "withTrajectory", "superyell", "kind", "count", "createdAt", "reportedAt", "reportFailed", "resolvedAt", "resolvedBy", "hasArchive", "caller", "callerApp", "conversation", "trace" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`guardrailsYell:read` returns the caller's yells. `guardrailsYell:admin` includes every yell in the active organization.", "permissions": [ "guardrailsYell:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read): View and resolve the Guardrails yells of your own sessions\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read) returns the caller's yells. [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin) includes every yell in the active organization." } }, "/api/openappa/yells/summary": { "get": { "operationId": "getOpenAppaYellsSummary", "tags": [ "OpenAPPA" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "unresolved": { "type": "number" }, "superyells": { "type": "number" } }, "required": [ "unresolved", "superyells" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`guardrailsYell:read` counts the caller's yells. `guardrailsYell:admin` counts every yell in the active organization.", "permissions": [ "guardrailsYell:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read): View and resolve the Guardrails yells of your own sessions\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read) counts the caller's yells. [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin) counts every yell in the active organization." } }, "/api/openappa/yells/{id}": { "get": { "operationId": "getOpenAppaYell", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "callerId": { "type": "string" }, "sessionId": { "type": "string" }, "toolCallId": { "type": "string" }, "message": { "type": "string" }, "withTrajectory": { "type": "boolean" }, "superyell": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "agent", "approval_waived", "block_waived" ] }, "count": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "reportedAt": { "nullable": true, "type": "string", "format": "date-time" }, "reportFailed": { "type": "boolean" }, "resolvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "resolvedBy": { "nullable": true, "type": "string" }, "hasArchive": { "type": "boolean" }, "caller": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "callerApp": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "conversation": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "createdAt" ], "additionalProperties": false }, "trace": { "nullable": true, "type": "object", "properties": { "llmSessionId": { "type": "string" }, "mcpToolCallId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "llmSessionId", "mcpToolCallId" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "callerId", "sessionId", "toolCallId", "message", "withTrajectory", "superyell", "kind", "count", "createdAt", "reportedAt", "reportFailed", "resolvedAt", "resolvedBy", "hasArchive", "caller", "callerApp", "conversation", "trace" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`guardrailsYell:read` permits a yell of the caller's sessions. `guardrailsYell:admin` permits any yell in the active organization.", "permissions": [ "guardrailsYell:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read): View and resolve the Guardrails yells of your own sessions\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read) permits a yell of the caller's sessions. [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin) permits any yell in the active organization." }, "patch": { "operationId": "updateOpenAppaYell", "tags": [ "OpenAPPA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "boolean" } }, "required": [ "resolved" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "callerId": { "type": "string" }, "sessionId": { "type": "string" }, "toolCallId": { "type": "string" }, "message": { "type": "string" }, "withTrajectory": { "type": "boolean" }, "superyell": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "agent", "approval_waived", "block_waived" ] }, "count": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "reportedAt": { "nullable": true, "type": "string", "format": "date-time" }, "reportFailed": { "type": "boolean" }, "resolvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "resolvedBy": { "nullable": true, "type": "string" }, "hasArchive": { "type": "boolean" }, "caller": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "callerApp": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "conversation": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "createdAt" ], "additionalProperties": false }, "trace": { "nullable": true, "type": "object", "properties": { "llmSessionId": { "type": "string" }, "mcpToolCallId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "llmSessionId", "mcpToolCallId" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "callerId", "sessionId", "toolCallId", "message", "withTrajectory", "superyell", "kind", "count", "createdAt", "reportedAt", "reportFailed", "resolvedAt", "resolvedBy", "hasArchive", "caller", "callerApp", "conversation", "trace" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "`guardrailsYell:read` resolves a yell of the caller's sessions. `guardrailsYell:admin` resolves any yell in the active organization.", "permissions": [ "guardrailsYell:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read): View and resolve the Guardrails yells of your own sessions\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read) resolves a yell of the caller's sessions. [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin) resolves any yell in the active organization." } }, "/api/openappa/yells/{id}/archive": { "get": { "operationId": "downloadOpenAppaYell", "tags": [ "OpenAPPA" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "static", "note": "`guardrailsYell:read` permits a yell of the caller's sessions. `guardrailsYell:admin` permits any yell in the active organization.", "permissions": [ "guardrailsYell:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read): View and resolve the Guardrails yells of your own sessions\n\n[`guardrailsYell:read`](/docs/reference/permissions#guardrailsYell:read) permits a yell of the caller's sessions. [`guardrailsYell:admin`](/docs/reference/permissions#guardrailsYell:admin) permits any yell in the active organization." } }, "/v1/openrouter/chat/completions": { "post": { "operationId": "openrouterChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with OpenRouter (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenrouterChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenrouterChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/openrouter/{agentId}/chat/completions": { "post": { "operationId": "openrouterChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with OpenRouter for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenrouterChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenrouterChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/roles": { "get": { "operationId": "getRoles", "tags": [ "Roles" ], "description": "Get all roles in the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`ac:read`](/docs/reference/permissions#ac:read): View custom roles and their permissions", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false }, { "schema": { "type": "string", "enum": [ "custom" ] }, "in": "query", "name": "kind", "required": false, "description": "Limit the list to one kind of role. `custom` leaves out the built-in roles, which cannot be edited." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "permission": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "predefined": { "type": "boolean" } }, "required": [ "id", "organizationId", "role", "name", "description", "permission", "createdAt", "updatedAt", "predefined" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "ac:read" ] } }, "post": { "operationId": "createRole", "tags": [ "Roles" ], "description": "Create a new custom role\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`ac:create`](/docs/reference/permissions#ac:create): Create new custom roles", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "type": "string", "maxLength": 200 }, "permission": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } } }, "required": [ "name", "permission" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "permission": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "predefined": { "type": "boolean" } }, "required": [ "id", "organizationId", "role", "name", "description", "permission", "createdAt", "updatedAt", "predefined" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "ac:create" ] } } }, "/api/roles/{roleId}": { "get": { "operationId": "getRole", "tags": [ "Roles" ], "description": "Get a specific role by ID\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`ac:read`](/docs/reference/permissions#ac:read): View custom roles and their permissions", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "admin", "platform_admin", "editor", "member" ] }, { "type": "string", "minLength": 1, "description": "Custom role ID (base62)" } ] }, "in": "path", "name": "roleId", "required": true, "description": "Predefined role name or custom role ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "permission": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "predefined": { "type": "boolean" } }, "required": [ "id", "organizationId", "role", "name", "description", "permission", "createdAt", "updatedAt", "predefined" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "ac:read" ] } }, "put": { "operationId": "updateRole", "tags": [ "Roles" ], "description": "Update a custom role\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`ac:update`](/docs/reference/permissions#ac:update): Modify custom role permissions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "type": "string", "maxLength": 200 }, "permission": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } } } } } } }, "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "admin", "platform_admin", "editor", "member" ] }, { "type": "string", "minLength": 1, "description": "Custom role ID (base62)" } ] }, "in": "path", "name": "roleId", "required": true, "description": "Predefined role name or custom role ID" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "role": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "permission": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" }, "predefined": { "type": "boolean" } }, "required": [ "id", "organizationId", "role", "name", "description", "permission", "createdAt", "updatedAt", "predefined" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "ac:update" ] } }, "delete": { "operationId": "deleteRole", "tags": [ "Roles" ], "description": "Delete a custom role\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`ac:delete`](/docs/reference/permissions#ac:delete): Delete custom roles", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "roleId", "required": true, "description": "Custom role ID (base62)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "ac:delete" ] } } }, "/api/organization": { "get": { "operationId": "getOrganization", "tags": [ "Organization" ], "description": "Get organization details\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/organization/default-model": { "get": { "operationId": "getOrganizationDefaultModel", "tags": [ "Organization" ], "description": "Get the model agents and chats on the organization default run on, and the tiers auto routing routes them across\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "displayName": { "type": "string" } }, "required": [ "id", "provider", "displayName" ], "additionalProperties": false }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tiers": { "type": "object", "properties": { "fast": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "displayName": { "type": "string" } }, "required": [ "id", "provider", "displayName" ], "additionalProperties": false }, "normal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "displayName": { "type": "string" } }, "required": [ "id", "provider", "displayName" ], "additionalProperties": false }, "smart": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "displayName": { "type": "string" } }, "required": [ "id", "provider", "displayName" ], "additionalProperties": false } }, "required": [ "fast", "normal", "smart" ], "additionalProperties": false } }, "required": [ "id", "name", "tiers" ], "additionalProperties": false } } }, "required": [ "model", "defaultAutoRouterId", "autoRouters" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/organization/appearance-settings": { "patch": { "operationId": "updateAppearanceSettings", "tags": [ "Organization" ], "description": "Update appearance settings\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "favicon": { "nullable": true, "type": "string" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[\\p{L}\\p{N}][\\p{L}\\p{N} .,'’\\-&()+:!?_/]*$" }, "ogDescription": { "nullable": true, "type": "string", "maxLength": 500 }, "footerText": { "nullable": true, "type": "string", "maxLength": 500 }, "chatLinks": { "nullable": true, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ] } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ] } } }, "required": [ "label", "pages" ] }, "chatErrorSupportMessage": { "nullable": true, "type": "string", "maxLength": 500 }, "slimChatErrorUi": { "type": "boolean" }, "chatPlaceholders": { "nullable": true, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80 } }, "animateChatPlaceholders": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "get": { "operationId": "getAppearanceSettings", "tags": [ "Organization" ], "description": "Get organization appearance settings\n\nAuthentication:\n\nNot required.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "favicon": { "nullable": true, "type": "string" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "animateChatPlaceholders": { "type": "boolean" } }, "required": [ "theme", "customFont", "logo", "logoDark", "favicon", "iconLogo", "iconLogoDark", "appName", "ogDescription", "footerText", "chatLinks", "chatErrorSupportMessage", "slimChatErrorUi", "animateChatPlaceholders" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/organization/security-settings": { "patch": { "operationId": "updateSecuritySettings", "tags": [ "Organization" ], "description": "Update security settings (default tool guardrails, chat file uploads)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/mcp-settings": { "patch": { "operationId": "updateMcpSettings", "tags": [ "Organization" ], "description": "Update MCP settings (online catalog availability, idle hibernation)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/skills-settings": { "patch": { "operationId": "updateSkillsSettings", "tags": [ "Organization" ], "description": "Update Skills settings (online catalog availability)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/mcp-runtime-tiers": { "get": { "operationId": "getMcpRuntimeTiers", "tags": [ "Organization" ], "description": "The organization's independent MCP CPU/RAM tiers\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryRequestMiBOverride": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiBOverride": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit", "memoryRequestMiB", "memoryLimitMiB" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateMcpRuntimeTiers", "tags": [ "Organization" ], "description": "Manage independent MCP CPU/RAM tiers\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "tiers": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "previousName": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryRequestMiBOverride": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiBOverride": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit", "memoryRequestMiB", "memoryLimitMiB" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/agent-runtime-tiers": { "get": { "operationId": "getAgentRuntimeTiers", "tags": [ "Organization" ], "description": "The organization's Agent Runtime tiers in effect, smallest first: each tier's name, CPU, memory, the spares it keeps ready, and the default tier\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "cpuRequest": { "type": "number" }, "cpuLimit": { "nullable": true, "type": "number" }, "warmSpares": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pooled": { "type": "boolean", "description": "Whether the tier keeps spare containers ready for its runs" }, "memoryRequestMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "memoryLimitMiB": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "memoryRequestMiBOverride": { "description": "Explicit memory request in MiB; absent when the request follows CPU", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "memoryLimitMiBOverride": { "description": "Explicit memory limit in MiB; absent when the limit follows CPU", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "workspaceGiB": { "nullable": true, "description": "Size of a run's workspace volume in GiB; null means the deployment's default", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit", "warmSpares", "pooled", "memoryRequestMiB", "memoryLimitMiB", "workspaceGiB" ], "additionalProperties": false } }, "defaultTier": { "type": "string" }, "defaultWorkspaceGiB": { "type": "number", "description": "The deployment's workspace volume size in GiB, which a tier that sets none gives its runs" } }, "required": [ "tiers", "defaultTier", "defaultWorkspaceGiB" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/organization/agent-settings/default-model-dependents": { "get": { "operationId": "getDefaultModelRuntimeDependents", "tags": [ "Organization" ], "description": "Agent Runtime agents the caller can read that run on the organization's default model (no usable model of their own), with the runtime each one uses and whether the caller may give it a model\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "modelId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "runtimeCommand": { "nullable": true, "type": "array", "items": { "type": "string" } }, "inferenceProtocol": { "type": "string", "enum": [ "openai_responses", "openai_chat", "anthropic" ] }, "claudeCodeAuthentication": { "type": "string", "enum": [ "provider", "subscription" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "canUpdate": { "type": "boolean" } }, "required": [ "runtimeCommand", "inferenceProtocol", "id", "name", "canUpdate" ], "additionalProperties": false } }, "hiddenBlockingCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "agents", "hiddenBlockingCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/organization/agent-settings": { "patch": { "operationId": "updateAgentSettings", "tags": [ "Organization" ], "description": "Update agent settings (default model or auto routing, default agent, skill slash commands, Agent Runtime tiers)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "pooled": { "type": "boolean" }, "workspaceGiB": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "previousName": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "name", "cpuRequest", "cpuLimit", "pooled" ], "additionalProperties": false } }, "defaultTier": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "tiers", "defaultTier" ], "additionalProperties": false }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/connection-settings": { "patch": { "operationId": "updateConnectionSettings", "tags": [ "Organization" ], "description": "Update /connection admin settings (default gateway, hidden clients, skills/LLM proxy availability)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ] } } }, "connectionDefaultClientId": { "nullable": true, "type": "string", "maxLength": 64 }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectionShownClientIds": { "nullable": true, "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectionShownProviders": { "not": {} }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 20000 }, "connectionBaseUrls": { "nullable": true, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url" ] } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/integration-settings": { "patch": { "operationId": "updateIntegrationSettings", "tags": [ "Organization" ], "description": "Customize the built-in integration catalogs: hide model providers, messaging channels, knowledge connectors, or coding agent templates, order coding agent templates, and override model provider labels. Omitted catalogs are left unchanged; null clears a catalog's overrides.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "popularAgentOverrides": { "nullable": true, "type": "object", "properties": { "claude-code": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "codex": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "opencode": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "hermes": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "openclaw": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "grok": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "kimi": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "copilot": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "custom-image": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/default-environment": { "patch": { "operationId": "updateDefaultEnvironment", "tags": [ "Organization" ], "description": "Configure the implicit default environment (the deployment target referenced by internal_mcp_catalog.environment_id = null). Pass null for name to reset to the built-in 'Default' label, or null for namespace to unset it. Omitted fields are left unchanged. When the namespace or network policy changes and the runtime is enabled, all default-environment MCP servers are reconciled.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`environment:update`](/docs/reference/permissions#environment:update): Modify deployment environments, including the org default environment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "nullable": true, "type": "string", "maxLength": 500 }, "namespace": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" }, "networkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$" } }, "allowedCidrs": { "maxItems": 500, "type": "array", "items": { "type": "string" } } } }, "restricted": { "not": {} }, "validationRegex": { "nullable": true, "type": "string", "maxLength": 1000 }, "trustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "environment:update" ] } } }, "/api/organization/auth-settings": { "patch": { "operationId": "updateAuthSettings", "tags": [ "Organization" ], "description": "Update organization Auth settings\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": 3600, "maximum": 31536000 }, "defaultMemberRole": { "nullable": true, "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/knowledge-settings": { "patch": { "operationId": "updateKnowledgeSettings", "tags": [ "Organization" ], "description": "Update knowledge settings (embedding model)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "embeddingModel": { "nullable": true, "type": "string", "minLength": 1 }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": 0, "maximum": 10 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": 0, "maximum": 1 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalModeInput" } ] } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/knowledge-settings/drop-embedding": { "post": { "operationId": "dropEmbeddingConfig", "tags": [ "Organization" ], "description": "Drop the embedding configuration, deleting all KB documents and resetting connector checkpoints\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/knowledge-settings/test-embedding": { "post": { "operationId": "testEmbeddingConnection", "tags": [ "Organization" ], "description": "Test the embedding connection by embedding a sample text\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "embeddingChatApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "embeddingModel": { "type": "string", "minLength": 1 } }, "required": [ "embeddingChatApiKeyId", "embeddingModel" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/knowledge-settings/test-reranker": { "post": { "operationId": "testRerankerConnection", "tags": [ "Organization" ], "description": "Test the reranker connection with a sample structured-output call\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rerankerChatApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "type": "string", "minLength": 1 } }, "required": [ "rerankerChatApiKeyId", "rerankerModel" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/knowledge-settings/keyword-ranking-status": { "get": { "operationId": "getKeywordRankingStatus", "tags": [ "Organization" ], "description": "Where BM25 keyword ranking stands for the organization: whether its corpus statistics cover every language with indexed documents (until they do, keyword search ranks that language with PostgreSQL's built-in ts_rank), when they were last rebuilt and when the next rebuild is due\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "pending", "no_documents" ] }, "lastRefreshedAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "nextRefreshAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "refreshing": { "type": "boolean" }, "lastRefreshFailed": { "type": "boolean" } }, "required": [ "status", "lastRefreshedAt", "nextRefreshAt", "refreshing", "lastRefreshFailed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/organization/knowledge-settings/test-ocr": { "post": { "operationId": "testOcrConnection", "tags": [ "Organization" ], "description": "Test the OCR configuration by sending a synthetic PDF page to the model\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ocrChatApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "type": "string", "minLength": 1 } }, "required": [ "ocrChatApiKeyId", "ocrModel" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/complete-onboarding": { "post": { "operationId": "completeOnboarding", "tags": [ "Organization" ], "description": "Mark organization onboarding as complete\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onboardingComplete": { "type": "boolean", "enum": [ true ] } }, "required": [ "onboardingComplete" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "analyticsInstanceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "logo": { "nullable": true, "type": "string" }, "logoDark": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "nullable": true, "type": "string" }, "onboardingComplete": { "type": "boolean" }, "onboardingSurveyCompletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "theme": { "type": "string", "enum": [ "modern-minimal", "clean-slate", "mono", "twitter", "tangerine", "bubblegum", "caffeine", "amber-minimal", "cosmic-night", "doom-64", "mocha-mousse", "nature", "sunset-horizon", "neo-brutalism", "vercel", "claude", "vintage-paper", "boxy-minimalistic", "catppuccin", "solarized-dark", "gruvbox-dark", "dracula-dark", "monokai-dark", "moonlight-dark" ] }, "customFont": { "type": "string", "enum": [ "lato", "inter", "open-sans", "roboto", "source-sans-pro", "jetbrains-mono" ] }, "onlineMcpCatalogEnabled": { "type": "boolean" }, "defaultPersonalAgentAccessAllTools": { "type": "boolean" }, "onlineSkillCatalogEnabled": { "type": "boolean" }, "skillMarketplaceAnonymousAccess": { "type": "boolean" }, "playwrightMcpEnabled": { "type": "boolean" }, "allowChatFileUploads": { "type": "boolean" }, "allowUnauthenticatedLlmProxyRequests": { "type": "boolean" }, "keepMediaInLogs": { "type": "boolean" }, "allowToolAutoAssignment": { "type": "boolean" }, "embeddingModel": { "nullable": true, "type": "string" }, "embeddingDimensions": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EmbeddingDimensions" } ] }, "embeddingChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rerankerModel": { "nullable": true, "type": "string" }, "ocrChatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ocrModel": { "nullable": true, "type": "string" }, "kbBm25K1": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbBm25B": { "nullable": true, "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "kbContextualRetrievalMode": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ContextualRetrievalMode" } ] }, "defaultLlmModel": { "nullable": true, "type": "string" }, "defaultLlmProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "defaultModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultLlmApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultAutoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRoutingEnabled": { "type": "boolean" }, "defaultFastModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultSmartModelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "defaultUserLimitValue": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "defaultUserLimitModel": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultUserLimitCleanupInterval": { "nullable": true, "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "defaultMemberRole": { "nullable": true, "type": "string" }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "favicon": { "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "ogDescription": { "nullable": true, "type": "string" }, "footerText": { "nullable": true, "type": "string" }, "chatLinks": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "label", "url" ], "additionalProperties": false } }, "onboardingWizard": { "nullable": true, "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 25 }, "pages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "image": { "nullable": true, "type": "string" }, "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } }, "required": [ "label", "pages" ], "additionalProperties": false }, "chatPlaceholders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "animateChatPlaceholders": { "type": "boolean" }, "iconLogo": { "nullable": true, "type": "string" }, "iconLogoDark": { "nullable": true, "type": "string" }, "chatErrorSupportMessage": { "nullable": true, "type": "string" }, "slimChatErrorUi": { "type": "boolean" }, "requireTwoFactor": { "type": "boolean" }, "sessionMaxAgeSeconds": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "oauthAccessTokenLifetimeSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 }, "connectionPageHidden": { "type": "boolean" }, "connectionDefaultMcpGatewayId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultLlmProxyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connectionDefaultClientId": { "nullable": true, "type": "string" }, "connectionShownClientIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionClientOrder": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionShownProviders": { "nullable": true, "type": "array", "items": { "type": "string" } }, "connectionBaseUrls": { "nullable": true, "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "default": "", "type": "string", "maxLength": 500 }, "isDefault": { "default": false, "type": "boolean" }, "visible": { "default": true, "type": "boolean" } }, "required": [ "url", "description", "isDefault", "visible" ], "additionalProperties": false } }, "connectionClientFutureProviders": { "nullable": true, "type": "object", "additionalProperties": { "type": "boolean" } }, "connectionClientProviderKeys": { "nullable": true, "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ], "additionalProperties": false } } }, "connectionSkillsEnabled": { "type": "boolean" }, "connectionLlmProxyEnabled": { "type": "boolean" }, "connectionPluginsEnabled": { "type": "boolean" }, "connectionRuntimeHandoffEnabled": { "type": "boolean" }, "connectionRuntimeHandoffInstructions": { "nullable": true, "type": "string" }, "modelProviderOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 }, "plans": { "type": "object", "properties": { "personal": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false }, "enterprise": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "displayName": { "nullable": true, "type": "string", "maxLength": 60 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "messagingChannelOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "knowledgeConnectorOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" } }, "additionalProperties": false } }, "popularAgentOverrides": { "nullable": true, "type": "object", "additionalProperties": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "defaultEnvironmentName": { "nullable": true, "type": "string" }, "defaultEnvironmentNamespace": { "nullable": true, "type": "string" }, "defaultEnvironmentDescription": { "nullable": true, "type": "string" }, "defaultNetworkPolicy": { "nullable": true, "type": "object", "properties": { "egressMode": { "type": "string", "enum": [ "off", "restricted", "unrestricted" ] }, "domainPreset": { "type": "string", "enum": [ "none", "common_dependencies", "package_managers" ] }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "allowedCidrs": { "type": "array", "items": { "type": "string" } } }, "required": [ "egressMode", "domainPreset", "allowedDomains", "allowedCidrs" ], "additionalProperties": false }, "mcpRuntimeTiers": { "nullable": true, "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32 }, "cpuRequest": { "type": "number", "minimum": 0.1, "maximum": 256 }, "cpuLimit": { "nullable": true, "type": "number", "minimum": 0.1, "maximum": 256 }, "memoryRequestMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "memoryLimitMiB": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name", "cpuRequest", "cpuLimit" ], "additionalProperties": false } } }, "required": [ "tiers" ], "additionalProperties": false }, "agentRuntimeTiers": { "nullable": true, "type": "object", "additionalProperties": {} }, "defaultEnvironmentValidationRegex": { "nullable": true, "type": "string" }, "defaultEnvironmentTrustedImageRegistries": { "nullable": true, "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9._:/-]+$" } }, "skillToolsEnabled": { "type": "boolean" }, "mcpIdleHibernationEnabled": { "type": "boolean" }, "newAppsDisabledByDefault": { "type": "boolean" }, "newAppsLockedByDefault": { "type": "boolean" } }, "required": [ "id", "name", "slug", "analyticsInstanceId", "logo", "logoDark", "createdAt", "metadata", "onboardingComplete", "onboardingSurveyCompletedAt", "theme", "customFont", "onlineMcpCatalogEnabled", "defaultPersonalAgentAccessAllTools", "onlineSkillCatalogEnabled", "skillMarketplaceAnonymousAccess", "playwrightMcpEnabled", "allowChatFileUploads", "allowUnauthenticatedLlmProxyRequests", "keepMediaInLogs", "allowToolAutoAssignment", "embeddingModel", "embeddingDimensions", "embeddingChatApiKeyId", "rerankerChatApiKeyId", "rerankerModel", "ocrChatApiKeyId", "ocrModel", "kbBm25K1", "kbBm25B", "kbContextualRetrievalMode", "defaultLlmModel", "defaultLlmProvider", "defaultModelId", "defaultLlmApiKeyId", "defaultAutoRouterId", "autoRoutingEnabled", "defaultFastModelId", "defaultSmartModelId", "defaultUserLimitValue", "defaultUserLimitModel", "defaultUserLimitCleanupInterval", "defaultMemberRole", "defaultAgentId", "favicon", "appName", "ogDescription", "footerText", "chatLinks", "onboardingWizard", "chatPlaceholders", "animateChatPlaceholders", "iconLogo", "iconLogoDark", "chatErrorSupportMessage", "slimChatErrorUi", "requireTwoFactor", "sessionMaxAgeSeconds", "oauthAccessTokenLifetimeSeconds", "connectionPageHidden", "connectionDefaultMcpGatewayId", "connectionDefaultLlmProxyId", "connectionDefaultClientId", "connectionShownClientIds", "connectionClientOrder", "connectionShownProviders", "connectionBaseUrls", "connectionClientFutureProviders", "connectionClientProviderKeys", "connectionSkillsEnabled", "connectionLlmProxyEnabled", "connectionPluginsEnabled", "connectionRuntimeHandoffEnabled", "connectionRuntimeHandoffInstructions", "modelProviderOverrides", "messagingChannelOverrides", "knowledgeConnectorOverrides", "popularAgentOverrides", "defaultEnvironmentName", "defaultEnvironmentNamespace", "defaultEnvironmentDescription", "defaultNetworkPolicy", "mcpRuntimeTiers", "agentRuntimeTiers", "defaultEnvironmentValidationRegex", "defaultEnvironmentTrustedImageRegistries", "skillToolsEnabled", "mcpIdleHibernationEnabled", "newAppsDisabledByDefault", "newAppsLockedByDefault" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/organization/onboarding-status": { "get": { "operationId": "getOnboardingStatus", "tags": [ "Organization" ], "description": "Check if organization onboarding is complete\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasLlmProxyLogs": { "type": "boolean" }, "hasMcpGatewayLogs": { "type": "boolean" } }, "required": [ "hasLlmProxyLogs", "hasMcpGatewayLogs" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/organization/members/signup-status": { "get": { "operationId": "getMemberSignupStatus", "tags": [ "Organization" ], "description": "Get which members have not completed signup (no account record). Pass `userIds` to ask about the members on screen instead of every member.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "userIds", "required": false, "description": "Only these members (comma-separated user IDs), such as the rows of one Users page. Without it, every member of the organization is checked." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pendingSignupMembers": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "image": { "nullable": true, "type": "string" }, "role": { "type": "string" }, "provider": { "nullable": true, "type": "string" }, "invitationId": { "nullable": true, "type": "string" } }, "required": [ "userId", "name", "email", "image", "role", "provider", "invitationId" ], "additionalProperties": false } } }, "required": [ "pendingSignupMembers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/organization/members/{userId}/pending-signup": { "delete": { "operationId": "deletePendingSignupMember", "tags": [ "Organization" ], "description": "Delete an auto-provisioned member who hasn't completed signup\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:delete`](/docs/reference/permissions#member:delete): Remove members from the organization", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:delete" ] } } }, "/api/organization/member-options": { "get": { "operationId": "getOrganizationMemberOptions", "tags": [ "Organization" ], "description": "Search visible organization member identities in bounded pages. The same directory visibility applies: member:read sees all members; other authenticated callers see only teammates.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nAll authenticated callers may search visible member identities. member:read returns the organization roster; other callers receive only teammates in the active organization.", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "default": "name_or_email", "type": "string", "enum": [ "name", "name_or_email" ] }, "in": "query", "name": "searchMode", "required": false }, { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "ids", "required": false }, { "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "emails", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "All authenticated callers may search visible member identities. member:read returns the organization roster; other callers receive only teammates in the active organization.", "permissions": [] } } }, "/api/organization/members/{idOrEmail}": { "get": { "operationId": "getOrganizationMember", "tags": [ "Organization" ], "description": "Get a member of the organization by user ID or email address\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:read`](/docs/reference/permissions#member:read): View organization members and their roles", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "idOrEmail", "required": true, "description": "User ID or email address" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:read" ] } } }, "/v1/perplexity/chat/completions": { "post": { "operationId": "perplexityChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Perplexity (uses default agent). Note: this endpoint does not support external tool calling; the /responses Agent API endpoint does.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/perplexity/{agentId}/chat/completions": { "post": { "operationId": "perplexityChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Perplexity for a specific agent. Note: this endpoint does not support external tool calling; the /responses Agent API endpoint does.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerplexityChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/perplexity/responses": { "post": { "operationId": "perplexityResponsesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with the Perplexity Agent API (uses default agent).\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for the Perplexity Agent API" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/perplexity/{agentId}/responses": { "post": { "operationId": "perplexityResponsesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with the Perplexity Agent API for a specific agent.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for the Perplexity Agent API" } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/plugins/{id}/transfer-ownership": { "post": { "operationId": "transferPluginOwnership", "tags": [ "Ownership" ], "description": "Transfer ownership to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins/labels/keys": { "get": { "operationId": "pluginLabelKeys", "tags": [ "Plugins" ], "description": "Get all label keys used by plugins\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins/labels/values": { "get": { "operationId": "pluginLabelValues", "tags": [ "Plugins" ], "description": "Get all label values used by plugins\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins": { "get": { "operationId": "getPlugins", "tags": [ "Plugins" ], "description": "List plugins for the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "sourceProvider", "sourceOrigin", "lastSyncedAt", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "fileCount" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createPlugin", "tags": [ "Plugins" ], "description": "Create a plugin. Hook configuration bytes are stored verbatim.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`plugin:create`](/docs/reference/permissions#plugin:create): Create plugins", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "default": "", "type": "string", "maxLength": 1000 }, "icon": { "description": "Emoji or base64 image data URL shown with the name.", "nullable": true, "type": "string" }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "files": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "content": { "type": "string", "maxLength": 1024000 }, "encoding": { "default": "utf8", "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "default": "100644", "type": "string", "enum": [ "100644", "100755" ] } }, "required": [ "path", "content" ] } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "displayName", "clientType", "files" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "plugin:create" ] } } }, "/api/plugins/github/marketplace/discover": { "post": { "operationId": "discoverGithubPluginMarketplace", "tags": [ "Plugins" ], "description": "Discover and normalize plugins advertised by a GitHub marketplace repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`plugin:create`](/docs/reference/permissions#plugin:create): Create plugins", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "ref": { "nullable": true, "type": "string", "minLength": 1 }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string", "minLength": 1 }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "marketplacePath": { "type": "string", "enum": [ ".claude-plugin/marketplace.json", ".github/plugin/marketplace.json", ".agents/plugins/marketplace.json", ".cursor-plugin/marketplace.json", "marketplace.json" ] } }, "required": [ "repoUrl" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string" }, "ref": { "nullable": true, "type": "string" }, "commitSha": { "type": "string" }, "marketplacePath": { "nullable": true, "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "marketplacePath": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "clientType": { "nullable": true, "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "sourceRepoUrl": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSubdir": { "type": "string" }, "sourceCommitSha": { "nullable": true, "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "supported": { "type": "boolean" }, "reason": { "nullable": true, "type": "string" } }, "required": [ "marketplacePath", "name", "description", "version", "clientType", "sourceRepoUrl", "sourceRef", "sourceSubdir", "sourceCommitSha", "fileCount", "supported", "reason" ], "additionalProperties": false } }, "reason": { "nullable": true, "type": "string" } }, "required": [ "repoUrl", "ref", "commitSha", "marketplacePath", "entries", "reason" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "plugin:create" ] } } }, "/api/plugins/github/marketplace/import": { "post": { "operationId": "importGithubPluginMarketplace", "tags": [ "Plugins" ], "description": "Import selected plugins from one reviewed GitHub marketplace snapshot\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`plugin:create`](/docs/reference/permissions#plugin:create): Create plugins", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "ref": { "nullable": true, "type": "string", "minLength": 1 }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string", "minLength": 1 }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "marketplacePath": { "nullable": true, "description": "The reviewed manifest path, or null to import plugin folders discovered in a repository without a marketplace manifest", "type": "string", "enum": [ ".claude-plugin/marketplace.json", ".github/plugin/marketplace.json", ".agents/plugins/marketplace.json", ".cursor-plugin/marketplace.json", "marketplace.json" ] }, "approvedCommitSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "trackingRef": { "nullable": true, "type": "string", "minLength": 1 }, "selected": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "default": "", "type": "string", "maxLength": 1000 }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "sourceRepoUrl": { "type": "string", "minLength": 1 }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSubdir": { "type": "string" }, "approvedSourceSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "exclude": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "name", "displayName", "clientType", "supportedPlatforms", "sourceRepoUrl", "sourceRef", "sourceSubdir", "approvedSourceSha" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "syncInterval": { "default": "1d", "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] } }, "required": [ "repoUrl", "marketplacePath", "approvedCommitSha", "trackingRef", "selected" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "error": { "type": "string" } }, "required": [ "name", "error" ], "additionalProperties": false } } }, "required": [ "created", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "plugin:create" ] } } }, "/api/plugins/github/preview": { "post": { "operationId": "previewGithubPlugin", "tags": [ "Plugins" ], "description": "Resolve a GitHub ref and preview the exact by-value plugin bytes\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`plugin:create`](/docs/reference/permissions#plugin:create): Create plugins", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "ref": { "nullable": true, "type": "string", "minLength": 1 }, "subdir": { "default": "", "type": "string" }, "exclude": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string", "minLength": 1 }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "repoUrl" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "sourceProvider": { "type": "string", "enum": [ "github", "gitlab" ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "requestedRef": { "nullable": true, "type": "string" }, "commitSha": { "type": "string" }, "subdir": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] } }, "required": [ "path", "content", "encoding", "mode" ], "additionalProperties": false } }, "skippedFiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "repo", "sourceProvider", "sourceOrigin", "requestedRef", "commitSha", "subdir", "files", "skippedFiles" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "plugin:create" ] } } }, "/api/plugins/github/import": { "post": { "operationId": "importGithubPlugin", "tags": [ "Plugins" ], "description": "Import and approve a plugin from an immutable GitHub commit\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`plugin:create`](/docs/reference/permissions#plugin:create): Create plugins", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "ref": { "nullable": true, "type": "string", "minLength": 1 }, "subdir": { "default": "", "type": "string" }, "exclude": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string", "minLength": 1 }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "default": "", "type": "string", "maxLength": 1000 }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "approvedCommitSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "trackingRef": { "nullable": true, "type": "string", "minLength": 1 } }, "required": [ "repoUrl", "displayName", "clientType", "approvedCommitSha" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "plugin:create" ] } } }, "/api/plugins/{id}/github/preview-update": { "post": { "operationId": "previewGithubPluginUpdate", "tags": [ "Plugins" ], "description": "Preview the latest tracked GitHub commit without changing approved bytes\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string", "minLength": 1 }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string" }, "sourceProvider": { "type": "string", "enum": [ "github", "gitlab" ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "requestedRef": { "nullable": true, "type": "string" }, "commitSha": { "type": "string" }, "subdir": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] } }, "required": [ "path", "content", "encoding", "mode" ], "additionalProperties": false } }, "skippedFiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "repo", "sourceProvider", "sourceOrigin", "requestedRef", "commitSha", "subdir", "files", "skippedFiles" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins/{id}/github/apply-update": { "post": { "operationId": "applyGithubPluginUpdate", "tags": [ "Plugins" ], "description": "Re-fetch and explicitly approve the latest tracked GitHub commit\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string", "minLength": 1 }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "approvedCommitSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" } }, "required": [ "approvedCommitSha" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins/{id}/github/sync": { "patch": { "operationId": "updatePluginGithubSync", "tags": [ "Plugins" ], "description": "Change or pause a Plugin Git sync schedule\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] } }, "required": [ "interval" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins/{id}/github/check": { "post": { "operationId": "triggerPluginGithubSync", "tags": [ "Plugins" ], "description": "Queue an immediate Plugin Git source check\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/plugins/{id}": { "get": { "operationId": "getPlugin", "tags": [ "Plugins" ], "description": "Get one plugin and its opaque files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updatePlugin", "tags": [ "Plugins" ], "description": "Update plugin metadata, GitHub source settings, or files. Access is edited through the resource permissions API.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "description": "Emoji or base64 image data URL shown with the name.", "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "githubSource": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1, "maxLength": 2048 }, "ref": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "syncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "authentication": { "type": "object", "properties": { "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "githubAppConfigId", "githubPatId" ] } }, "required": [ "repoUrl", "ref", "syncInterval" ] }, "files": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "content": { "type": "string", "maxLength": 1024000 }, "encoding": { "default": "utf8", "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "default": "100644", "type": "string", "enum": [ "100644", "100755" ] } }, "required": [ "path", "content" ] } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "contentHash": { "type": "string" }, "sourceKind": { "type": "string", "enum": [ "manual", "github" ] }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceRef": { "nullable": true, "type": "string" }, "sourceSha": { "nullable": true, "type": "string" }, "sourceSubdir": { "nullable": true, "type": "string" }, "sourceExclude": { "type": "array", "items": { "type": "string" } }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "sourceMarketplacePath": { "nullable": true, "type": "string" }, "sourceMarketplacePluginName": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "sourceOrigin": { "nullable": true, "type": "string" }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "pendingSourceSha": { "nullable": true, "type": "string" }, "pendingContentHash": { "nullable": true, "type": "string" }, "pendingDetectedAt": { "nullable": true, "type": "string", "format": "date-time" }, "sourceId": { "nullable": true, "type": "string" }, "approvedContentHash": { "nullable": true, "type": "string" }, "approvedAt": { "nullable": true, "type": "string", "format": "date-time" }, "approvedBy": { "nullable": true, "type": "string" }, "enabled": { "type": "boolean" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "mode": { "type": "string", "enum": [ "100644", "100755" ] }, "digest": { "type": "string" } }, "required": [ "id", "pluginId", "path", "content", "encoding", "mode", "digest" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "clientType", "supportedPlatforms", "pluginSlug", "displayName", "description", "icon", "contentHash", "sourceKind", "sourceRepo", "sourceRef", "sourceSha", "sourceSubdir", "sourceExclude", "sourceMarketplaceRepo", "sourceMarketplacePath", "sourceMarketplacePluginName", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "sourceOrigin", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "pendingSourceSha", "pendingContentHash", "pendingDetectedAt", "sourceId", "approvedContentHash", "approvedAt", "approvedBy", "enabled", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "teams", "users", "labels", "createdBy", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deletePlugin", "tags": [ "Plugins" ], "description": "Delete a plugin\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/plugins": { "get": { "operationId": "getPluginSkills", "tags": [ "Skills" ], "description": "List the portable Skills embedded in the plugins visible to the caller.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ] }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginName": { "type": "string" }, "pluginSlug": { "type": "string" }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "pluginEnabled": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "skillPath": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usageUserCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "source", "pluginId", "pluginName", "pluginSlug", "sourceRepo", "sourceMarketplaceRepo", "pluginEnabled", "scope", "clientType", "supportedPlatforms", "skillPath", "name", "description", "compatibility", "fileCount", "usageCount", "usageUserCount", "lastUsedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/plugins/{pluginId}/usage-statistics": { "get": { "operationId": "getPluginSkillUsageStatistics", "tags": [ "Skills" ], "description": "Get recent activation statistics for one Skill from an accessible plugin.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "skillPath", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "pluginId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "user", "service_account", "unattributed" ] }, "total": { "type": "number" } }, "required": [ "userId", "name", "kind", "total" ], "additionalProperties": false } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "userId": { "nullable": true, "type": "string" }, "count": { "type": "number" } }, "required": [ "date", "userId", "count" ], "additionalProperties": false } } }, "required": [ "since", "users", "daily" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/plugins/{pluginId}": { "get": { "operationId": "getPluginSkill", "tags": [ "Skills" ], "description": "Read one Skill embedded in a plugin, with its bundled resource files.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string", "maxLength": 500 }, "in": "query", "name": "skillPath", "required": false, "description": "Parent directory of the SKILL.md inside the plugin; omit for a root-level skill." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "pluginId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "plugin" ] }, "pluginId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginName": { "type": "string" }, "pluginSlug": { "type": "string" }, "sourceRepo": { "nullable": true, "type": "string" }, "sourceMarketplaceRepo": { "nullable": true, "type": "string" }, "pluginEnabled": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "clientType": { "type": "string", "enum": [ "claude-code", "claude-desktop", "copilot-cli", "codex", "cursor" ] }, "supportedPlatforms": { "type": "array", "items": { "type": "string", "enum": [ "posix", "windows" ] } }, "skillPath": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "fileCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usageUserCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "manifest": { "type": "string" }, "content": { "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "kind": { "type": "string", "enum": [ "script", "reference", "asset" ] } }, "required": [ "path", "content", "encoding", "kind" ], "additionalProperties": false } } }, "required": [ "source", "pluginId", "pluginName", "pluginSlug", "sourceRepo", "sourceMarketplaceRepo", "pluginEnabled", "scope", "clientType", "supportedPlatforms", "skillPath", "name", "description", "compatibility", "fileCount", "usageCount", "usageUserCount", "lastUsedAt", "manifest", "content", "allowedTools", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/projects/{id}/transfer-ownership": { "post": { "operationId": "transferProjectOwnership", "tags": [ "Ownership" ], "description": "Transfer ownership to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:update`](/docs/reference/permissions#project:update): Edit project descriptions, instructions, sharing, and schedules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:update" ] } } }, "/api/projects/labels/keys": { "get": { "operationId": "projectLabelKeys", "tags": [ "Projects" ], "description": "Get all label keys used by projects\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/projects/labels/values": { "get": { "operationId": "projectLabelValues", "tags": [ "Projects" ], "description": "Get all label values used by projects\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/projects": { "post": { "operationId": "createProject", "tags": [ "Projects" ], "description": "Create a project. Files produced in its chats are owned by the project rather than the individual author.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:create`](/docs/reference/permissions#project:create): Create projects and schedules, and trigger schedule runs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "nullable": true, "type": "string", "maxLength": 200 }, "icon": { "nullable": true, "type": "string", "maxLength": 1000000 }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "ownerName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "conversationCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "nullable": true, "type": "string", "enum": [ "organization", "team", "user" ] }, "shareTeamNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "icon", "viewerRole", "ownerName", "createdBy", "labels", "conversationCount", "visibility", "shareTeamNames", "shareUserNames", "pinnedAt", "createdAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:create" ] } }, "get": { "operationId": "getProjects", "tags": [ "Projects" ], "description": "List projects the caller can see. `scope` is the project's share visibility: `personal` (private), `team` (shared with teams — narrow with `teamIds`), or `org` (org-wide); omitted = all visible. Admins additionally filter `personal` by owner via `authorIds` / `excludeAuthorIds` (ignored for non-admins). `search` matches name + description. `status=deleted` returns the org-wide soft-deleted projects for a project admin (empty for everyone else); the other filters do not apply to that slice. Paginated: owner-first, then newest, then id.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "teamIds", "required": false, "description": "Team IDs (comma-separated); only used when scope=team." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "authorIds", "required": false, "description": "Owner user IDs (comma-separated). Admin-only; used with scope=personal." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "excludeAuthorIds", "required": false, "description": "Exclude owner user IDs (comma-separated). Admin-only; used with scope=personal." }, { "schema": { "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Lifecycle slice: `active` (default) or `deleted` (project admins only; org-wide soft-deleted projects for the restore view)." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "type": "boolean" }, "in": "query", "name": "pinned", "required": false, "description": "Only return projects the current user has pinned (true) or has not pinned (false). Omit for both." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "ownerName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "conversationCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "nullable": true, "type": "string", "enum": [ "organization", "team", "user" ] }, "shareTeamNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "icon", "viewerRole", "ownerName", "createdBy", "labels", "conversationCount", "visibility", "shareTeamNames", "shareUserNames", "pinnedAt", "createdAt", "deletedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/projects/from-conversation": { "post": { "operationId": "createProjectFromConversation", "tags": [ "Projects" ], "description": "Turn an existing chat into a project: create the project, move the chat into it, and re-point the chat's files to the project. Only the chat's owner may do this, and only for a user chat not already in a project. `name` defaults to the chat title.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:create`](/docs/reference/permissions#project:create): Create projects and schedules, and trigger schedule runs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "nullable": true, "type": "string", "maxLength": 200 }, "icon": { "nullable": true, "type": "string", "maxLength": 1000000 }, "labels": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } }, "required": [ "conversationId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "ownerName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "conversationCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "nullable": true, "type": "string", "enum": [ "organization", "team", "user" ] }, "shareTeamNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "icon", "viewerRole", "ownerName", "createdBy", "labels", "conversationCount", "visibility", "shareTeamNames", "shareUserNames", "pinnedAt", "createdAt", "deletedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:create" ] } } }, "/api/projects/{id}": { "get": { "operationId": "getProject", "tags": [ "Projects" ], "description": "Project detail. Share team ids are included for the owner only.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "ownerName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "conversationCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "nullable": true, "type": "string", "enum": [ "organization", "team", "user" ] }, "shareTeamNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "shareTeamIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultAgent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "icon", "viewerRole", "ownerName", "createdBy", "labels", "conversationCount", "visibility", "shareTeamNames", "shareUserNames", "pinnedAt", "createdAt", "deletedAt", "shareTeamIds", "shareUserIds", "defaultAgent" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } }, "patch": { "operationId": "updateProject", "tags": [ "Projects" ], "description": "Update a project's name, description, icon, and/or default agent (owner or a project admin). Only the provided fields change. The default agent must be an organization-wide chat agent; null clears it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:update`](/docs/reference/permissions#project:update): Edit project descriptions, instructions, sharing, and schedules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "nullable": true, "type": "string", "maxLength": 200 }, "icon": { "nullable": true, "type": "string", "maxLength": 1000000 }, "defaultAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:update" ] } }, "delete": { "operationId": "deleteProject", "tags": [ "Projects" ], "description": "Soft-delete a project (owner or a project admin). Its chats detach and survive as ordinary conversations; its files and scheduled tasks are retained but hidden, and a project admin can restore them. Nothing is purged.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:delete`](/docs/reference/permissions#project:delete): Delete projects and schedules", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:delete" ] } } }, "/api/projects/bulk": { "delete": { "operationId": "bulkDeleteProjects", "tags": [ "Projects" ], "description": "Soft-delete several projects in one request (owner or project admin per project). As with the single-project delete, their chats detach and survive as ordinary conversations, and their files and scheduled tasks are retained but hidden. Nothing is purged, and a project the caller may not delete is reported in `failed` while the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:delete`](/docs/reference/permissions#project:delete): Delete projects and schedules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:delete" ] } } }, "/api/projects/{id}/restore": { "post": { "operationId": "restoreProject", "tags": [ "Projects" ], "description": "Restore a soft-deleted project (project admins only). Brings back its retained files and scheduled tasks (schedules resume forward-only, no catch-up runs); chats do NOT re-attach, so the restored project reports zero chats. 404 if there is no soft-deleted project with that id in the org. Deleting frees the display name, so if the owner has since taken it, pass `name` to restore under a different one; restoring into a name that is still taken is a 409.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:delete`](/docs/reference/permissions#project:delete): Delete projects and schedules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "name": { "description": "Rename the project as it is restored. Use this when its original name was taken while it was deleted.", "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "viewerRole": { "type": "string", "enum": [ "owner", "shared", "admin" ] }, "ownerName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "conversationCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "visibility": { "nullable": true, "type": "string", "enum": [ "organization", "team", "user" ] }, "shareTeamNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserNames": { "nullable": true, "type": "array", "items": { "type": "string" } }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "shareTeamIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "shareUserIds": { "nullable": true, "type": "array", "items": { "type": "string" } }, "defaultAgent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "icon", "viewerRole", "ownerName", "createdBy", "labels", "conversationCount", "visibility", "shareTeamNames", "shareUserNames", "pinnedAt", "createdAt", "deletedAt", "shareTeamIds", "shareUserIds", "defaultAgent" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:delete" ] } } }, "/api/projects/{id}/permanent": { "delete": { "operationId": "permanentlyDeleteProject", "tags": [ "Projects" ], "description": "Permanently destroy a soft-deleted project (global admins only). Irreversible, with no grace period: the project, its files (records and stored contents), pins, share configuration, and scheduled tasks are all destroyed. Its chats are unaffected — they detached when it was deleted and survive as ordinary conversations. 404 if there is no soft-deleted project with that id in the org, which is also the answer when the project is still live or the caller is not a global admin. Restore wins a race: if a restore commits first, this returns 404 and the project stays.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRestricted to the built-in Admin and Platform Admin roles. No permission grants it: [`project:delete`](/docs/reference/permissions#project:delete), `project:admin`, and ownership of the project all reach the trash, not past it, and a service account never qualifies. A caller without it gets 404, not 403, so the endpoint never confirms the project exists.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Restricted to the built-in Admin and Platform Admin roles. No permission grants it: `project:delete`, `project:admin`, and ownership of the project all reach the trash, not past it, and a service account never qualifies. A caller without it gets 404, not 403, so the endpoint never confirms the project exists.", "permissions": [] } } }, "/api/projects/{id}/files": { "get": { "operationId": "getProjectFiles", "tags": [ "Projects" ], "description": "Files owned by the project, readable by anyone with project access.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "downloadRef": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time" }, "downloadable": { "type": "boolean" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "nullable": true, "type": "string" } }, "required": [ "id", "downloadRef", "filename", "mimeType", "sizeBytes", "createdAt", "downloadable", "projectId", "projectName" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } }, "post": { "operationId": "uploadProjectFiles", "tags": [ "Projects" ], "description": "Upload one file into the project (drag-and-drop on the Files panel). The bytes are base64-encoded in the body; a colliding name is auto-renamed.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string" }, "dataBase64": { "type": "string", "minLength": 1 } }, "required": [ "name", "mimeType", "dataBase64" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "filename": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "id", "filename", "mimeType" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/projects/{id}/instructions": { "get": { "operationId": "getProjectInstructions", "tags": [ "Projects" ], "description": "The project's instructions (markdown). Readable by anyone with project access; empty until the owner first saves it. The content is injected into the system prompt of every chat in the project.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } }, "put": { "operationId": "setProjectInstructions", "tags": [ "Projects" ], "description": "Set the project's instructions (owner only). The first save creates the instructions file; saving empty content keeps it but injects nothing.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:update`](/docs/reference/permissions#project:update): Edit project descriptions, instructions, sharing, and schedules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 100000 } }, "required": [ "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:update" ] } } }, "/api/projects/{id}/conversations": { "get": { "operationId": "getProjectConversations", "tags": [ "Projects" ], "description": "All chats in a project the caller can read. Chats authored by others require `read` on every chat (a grant at `*` on `conversation`); without it the caller sees only their own. `readOnly` marks chats authored by someone else (viewable, never writable).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "authorUserId": { "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "readOnly": { "type": "boolean" }, "scheduleTriggerId": { "nullable": true, "type": "string" }, "scheduleRunId": { "nullable": true, "type": "string" }, "scheduleName": { "nullable": true, "type": "string" } }, "required": [ "id", "title", "authorUserId", "authorName", "origin", "lastMessageAt", "createdAt", "readOnly", "scheduleTriggerId", "scheduleRunId", "scheduleName" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/projects/{id}/runs": { "get": { "operationId": "getProjectRuns", "tags": [ "Projects" ], "description": "All run sessions in a project the caller can read. Sessions started by others require `read` on every chat (a grant at `*` on `conversation`); all non-owner views are read-only.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "enum": [ "user", "team", "organization", "oauthClient", "serviceAccount", "system" ] }, "actorId": { "type": "string" }, "actorUserId": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workloadName": { "type": "string" }, "backend": { "type": "string", "enum": [ "kubernetes" ] }, "runtimeScope": { "type": "string" }, "runtimeLimits": { "nullable": true, "type": "object", "properties": { "tier": { "nullable": true, "type": "string", "minLength": 1, "maxLength": 32 }, "idleTimeoutMinutes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxDurationHours": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "maxCostUsd": { "nullable": true, "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "workspaceGiB": { "description": "Size of the run's workspace volume in GiB, recorded when the workspace was created. Absent on runs whose workspace predates recorded sizes.", "type": "number", "minimum": 0 } }, "required": [ "tier", "idleTimeoutMinutes", "maxDurationHours", "maxCostUsd" ], "additionalProperties": false }, "attentionState": { "anyOf": [ { "type": "string", "enum": [ "input_required", "auth_required" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "virtualApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gatewayTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "nullable": true, "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "TASK_STATE_UNSPECIFIED", "TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_COMPLETED", "TASK_STATE_FAILED", "TASK_STATE_CANCELED", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED" ] }, "statusReason": { "nullable": true, "type": "string" }, "failure": { "nullable": true, "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 160 }, "retriable": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "code", "retriable", "message" ], "additionalProperties": false }, "stateChangedAt": { "nullable": true, "type": "string", "format": "date-time" }, "hardDeadlineAt": { "type": "string", "format": "date-time" }, "lastModelActivityAt": { "nullable": true, "type": "string", "format": "date-time" }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "llmSessionId": { "type": "string", "description": "Key of the run's LLM logs (/llm/logs/:id): the session id its runtime sends" }, "prompt": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "icon": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "icon" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "terminalRetained": { "type": "boolean" }, "portForwardCommand": { "nullable": true, "type": "string" }, "workspace": { "nullable": true, "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "idle", "suspending", "suspended", "resuming", "deleting", "deleted" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "idleAt": { "nullable": true, "type": "string", "format": "date-time" }, "connection": { "nullable": true, "type": "object", "properties": { "hostname": { "type": "string" }, "shellCommand": { "type": "string" } }, "required": [ "hostname", "shellCommand" ], "additionalProperties": false } }, "required": [ "state", "expiresAt", "idleAt", "connection" ], "additionalProperties": false }, "viewerRole": { "type": "string", "enum": [ "owner", "shared" ] }, "canAttach": { "type": "boolean" }, "startupProgress": { "nullable": true, "type": "object", "properties": { "phase": { "type": "string", "enum": [ "queued", "scheduling", "pulling", "starting", "attaching" ] }, "message": { "type": "string" }, "detail": { "nullable": true, "type": "string" }, "resourceName": { "nullable": true, "type": "string" } }, "required": [ "phase", "message", "detail", "resourceName" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "taskId", "agentId", "actorKind", "actorId", "actorUserId", "title", "pinnedAt", "projectId", "workloadName", "backend", "runtimeScope", "runtimeLimits", "attentionState", "virtualApiKeyId", "gatewayTokenId", "startedAt", "endedAt", "state", "statusReason", "failure", "stateChangedAt", "hardDeadlineAt", "lastModelActivityAt", "sessionId", "llmSessionId", "prompt", "agent", "projectName", "projectIcon", "terminalRetained", "viewerRole" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read", "project:read" ] } } }, "/api/projects/{id}/pin": { "put": { "operationId": "pinProject", "tags": [ "Projects" ], "description": "Pin a project to the current user's sidebar. Personal — does not affect other members. Any user who can read the project may pin it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } }, "delete": { "operationId": "unpinProject", "tags": [ "Projects" ], "description": "Remove the current user's pin on a project. Idempotent; allowed even if the project was since unshared from the user.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/projects/{id}/apps": { "get": { "operationId": "getProjectApps", "tags": [ "Projects" ], "description": "Apps linked into the project. Each member sees only the linked apps they can read themselves.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "nullable": true, "type": "string" }, "description": { "nullable": true, "type": "string" }, "linkedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "linkedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read", "project:read" ] } } }, "/api/projects/{id}/apps/{appId}": { "put": { "operationId": "linkProjectApp", "tags": [ "Projects" ], "description": "Link an app into the project. Any project member who can read the app may link it; the app keeps its own permissions. Idempotent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read", "project:read" ] } }, "delete": { "operationId": "unlinkProjectApp", "tags": [ "Projects" ], "description": "Unlink an app from the project. The app itself is not changed.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "appId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read", "project:read" ] } } }, "/api/credentials/{key}/github/start": { "post": { "operationId": "startGitHubUserConnection", "tags": [ "Credentials" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorizationUrl": { "type": "string" } }, "required": [ "authorizationUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/credentials/github/callback": { "post": { "operationId": "completeGitHubUserConnection", "tags": [ "Credentials" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 1, "maxLength": 256 }, "code": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "state", "code" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "login": { "type": "string" }, "configured": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "login", "configured" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials" } }, "/api/credentials": { "get": { "operationId": "listRuntimeCredentials", "tags": [ "Credentials" ], "description": "List reusable credentials available to platform integrations\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`credential:read`](/docs/reference/permissions#credential:read): Open Credentials", "parameters": [ { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "secret", "github_app", "github_app_user", "gitlab_token" ] }, "githubUrl": { "nullable": true, "type": "string" }, "gitlabUrl": { "nullable": true, "type": "string" }, "appId": { "nullable": true, "type": "string" }, "installationId": { "nullable": true, "type": "string" }, "githubClientId": { "nullable": true, "type": "string" }, "githubAppCredentialKey": { "nullable": true, "type": "string" }, "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "builtIn": { "type": "boolean" }, "allowPersonal": { "type": "boolean" }, "allowOrganization": { "type": "boolean" }, "personalConfigured": { "type": "boolean" }, "organizationConfigured": { "type": "boolean" } }, "required": [ "id", "kind", "githubUrl", "gitlabUrl", "appId", "installationId", "githubClientId", "githubAppCredentialKey", "key", "name", "description", "icon", "builtIn", "allowPersonal", "allowOrganization", "personalConfigured", "organizationConfigured" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "credential:read" ] } }, "post": { "operationId": "createRuntimeCredential", "tags": [ "Credentials" ], "description": "Create a credential definition\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nChecked dynamically based on the credential being created. A credential just for the caller (`allowPersonal: true`, `allowOrganization: false`, no `initialGrants`) needs no permission, and only its author can reach it. Organization credentials and credentials created with grants require [`credential:create`](/docs/reference/permissions#credential:create).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z][a-z0-9._-]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "kind": { "type": "string", "enum": [ "secret", "github_app", "github_app_user", "gitlab_token" ] }, "githubUrl": { "nullable": true, "type": "string" }, "appId": { "nullable": true, "type": "string" }, "installationId": { "nullable": true, "type": "string" }, "githubClientId": { "nullable": true, "type": "string" }, "githubAppCredentialKey": { "nullable": true, "type": "string" }, "gitlabUrl": { "nullable": true, "type": "string" }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 }, "allowPersonal": { "type": "boolean" }, "allowOrganization": { "type": "boolean" }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "key", "name" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "github_app", "github_app_user", "gitlab_token" ] }, "githubUrl": { "nullable": true, "type": "string" }, "appId": { "nullable": true, "type": "string" }, "installationId": { "nullable": true, "type": "string" }, "githubClientId": { "nullable": true, "type": "string" }, "githubAppCredentialKey": { "nullable": true, "type": "string" }, "gitlabUrl": { "nullable": true, "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "allowPersonal": { "type": "boolean" }, "allowOrganization": { "type": "boolean" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "key", "name", "kind", "githubUrl", "appId", "installationId", "githubClientId", "githubAppCredentialKey", "gitlabUrl", "description", "icon", "allowPersonal", "allowOrganization", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Checked dynamically based on the credential being created. A credential just for the caller (`allowPersonal: true`, `allowOrganization: false`, no `initialGrants`) needs no permission, and only its author can reach it. Organization credentials and credentials created with grants require `credential:create`.", "permissions": [] } } }, "/api/credentials/{key}/usage": { "get": { "operationId": "getRuntimeCredentialUsage", "tags": [ "Credentials" ], "description": "List resources using a saved credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "mcp", "skill", "plugin", "knowledge", "copilot" ] } }, "required": [ "id", "name", "kind" ], "additionalProperties": false } }, "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "resources", "agents" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/credentials/{key}": { "patch": { "operationId": "updateRuntimeCredential", "tags": [ "Credentials" ], "description": "Update a credential definition\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "githubUrl": { "nullable": true, "type": "string" }, "gitlabUrl": { "nullable": true, "type": "string" }, "appId": { "nullable": true, "type": "string" }, "installationId": { "nullable": true, "type": "string" }, "githubClientId": { "nullable": true, "type": "string" }, "githubAppCredentialKey": { "nullable": true, "type": "string" }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string", "maxLength": 700000 } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "github_app", "github_app_user", "gitlab_token" ] }, "githubUrl": { "nullable": true, "type": "string" }, "appId": { "nullable": true, "type": "string" }, "installationId": { "nullable": true, "type": "string" }, "githubClientId": { "nullable": true, "type": "string" }, "githubAppCredentialKey": { "nullable": true, "type": "string" }, "gitlabUrl": { "nullable": true, "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "allowPersonal": { "type": "boolean" }, "allowOrganization": { "type": "boolean" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "key", "name", "kind", "githubUrl", "appId", "installationId", "githubClientId", "githubAppCredentialKey", "gitlabUrl", "description", "icon", "allowPersonal", "allowOrganization", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteRuntimeCredential", "tags": [ "Credentials" ], "description": "Delete a credential definition\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/credentials/{key}/personal": { "put": { "operationId": "setPersonalRuntimeCredentialConnection", "tags": [ "Credentials" ], "description": "Connect a personal credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "value" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "enum": [ true ] } }, "required": [ "configured" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deletePersonalRuntimeCredentialConnection", "tags": [ "Credentials" ], "description": "Disconnect a personal credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/credentials/{key}/organization": { "put": { "operationId": "setOrganizationRuntimeCredentialConnection", "tags": [ "Credentials" ], "description": "Connect an organization credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "value" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "enum": [ true ] } }, "required": [ "configured" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteOrganizationRuntimeCredentialConnection", "tags": [ "Credentials" ], "description": "Disconnect an organization credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "key", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/schedule-triggers": { "get": { "operationId": "getScheduleTriggers", "tags": [ "Schedule Triggers" ], "description": "List scheduled agent triggers\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "enabled", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "actorUserIds", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "agentIds", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "projectId", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "showAll", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageTemplate": { "type": "string" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" }, "actorUserId": { "type": "string" }, "lastExecutedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "agentType": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "agentId", "projectId", "messageTemplate", "cronExpression", "timezone", "enabled", "actorUserId", "lastExecutedAt", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } }, "post": { "operationId": "createScheduleTrigger", "tags": [ "Schedule Triggers" ], "description": "Create a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:create`](/docs/reference/permissions#project:create): Create projects and schedules, and trigger schedule runs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "default": true, "type": "boolean" }, "cronExpression": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "messageTemplate": { "type": "string", "minLength": 1 } }, "required": [ "name", "projectId", "cronExpression", "timezone", "messageTemplate" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageTemplate": { "type": "string" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" }, "actorUserId": { "type": "string" }, "lastExecutedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "agentType": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "agentId", "projectId", "messageTemplate", "cronExpression", "timezone", "enabled", "actorUserId", "lastExecutedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:create" ] } } }, "/api/schedule-triggers/{id}": { "get": { "operationId": "getScheduleTrigger", "tags": [ "Schedule Triggers" ], "description": "Get a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageTemplate": { "type": "string" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" }, "actorUserId": { "type": "string" }, "lastExecutedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "agentType": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "agentId", "projectId", "messageTemplate", "cronExpression", "timezone", "enabled", "actorUserId", "lastExecutedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } }, "put": { "operationId": "updateScheduleTrigger", "tags": [ "Schedule Triggers" ], "description": "Update a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:update`](/docs/reference/permissions#project:update): Edit project descriptions, instructions, sharing, and schedules", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "cronExpression": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "messageTemplate": { "type": "string", "minLength": 1 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageTemplate": { "type": "string" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" }, "actorUserId": { "type": "string" }, "lastExecutedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "agentType": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "agentId", "projectId", "messageTemplate", "cronExpression", "timezone", "enabled", "actorUserId", "lastExecutedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:update" ] } }, "delete": { "operationId": "deleteScheduleTrigger", "tags": [ "Schedule Triggers" ], "description": "Delete a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:delete`](/docs/reference/permissions#project:delete): Delete projects and schedules", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:delete" ] } } }, "/api/schedule-triggers/{id}/enable": { "post": { "operationId": "enableScheduleTrigger", "tags": [ "Schedule Triggers" ], "description": "Enable a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:update`](/docs/reference/permissions#project:update): Edit project descriptions, instructions, sharing, and schedules", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageTemplate": { "type": "string" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" }, "actorUserId": { "type": "string" }, "lastExecutedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "agentType": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "agentId", "projectId", "messageTemplate", "cronExpression", "timezone", "enabled", "actorUserId", "lastExecutedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:update" ] } } }, "/api/schedule-triggers/{id}/disable": { "post": { "operationId": "disableScheduleTrigger", "tags": [ "Schedule Triggers" ], "description": "Disable a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:update`](/docs/reference/permissions#project:update): Edit project descriptions, instructions, sharing, and schedules", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "messageTemplate": { "type": "string" }, "cronExpression": { "type": "string" }, "timezone": { "type": "string" }, "enabled": { "type": "boolean" }, "actorUserId": { "type": "string" }, "lastExecutedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "actor": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "agentType": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "agentId", "projectId", "messageTemplate", "cronExpression", "timezone", "enabled", "actorUserId", "lastExecutedAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:update" ] } } }, "/api/schedule-triggers/{id}/run-now": { "post": { "operationId": "runScheduleTriggerNow", "tags": [ "Schedule Triggers" ], "description": "Run a scheduled agent trigger immediately\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:create`](/docs/reference/permissions#project:create): Create projects and schedules, and trigger schedule runs", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "triggerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runKind": { "type": "string", "enum": [ "due", "manual" ] }, "status": { "type": "string", "enum": [ "running", "success", "failed", "cancelled" ] }, "initiatedByUserId": { "nullable": true, "type": "string" }, "chatConversationId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runtimeTaskId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "nullable": true, "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "error": { "nullable": true, "type": "string" }, "blockedBy": { "nullable": true, "type": "object", "properties": { "phase": { "type": "string", "enum": [ "starting", "running", "stopping" ] }, "runId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runtimeTaskId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "elapsedSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deadline": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "maximumDurationSeconds": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "phase", "runId", "runtimeTaskId", "startedAt", "elapsedSeconds", "deadline", "maximumDurationSeconds" ], "additionalProperties": false }, "artifact": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "triggerId", "runKind", "status", "initiatedByUserId", "chatConversationId", "runtimeTaskId", "startedAt", "completedAt", "error", "blockedBy", "artifact", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:create" ] } } }, "/api/schedule-triggers/{id}/runs": { "get": { "operationId": "getScheduleTriggerRuns", "tags": [ "Schedule Triggers" ], "description": "List runs for a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "running", "success", "failed", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "due", "manual" ] }, "in": "query", "name": "runKind", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "triggerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runKind": { "type": "string", "enum": [ "due", "manual" ] }, "status": { "type": "string", "enum": [ "running", "success", "failed", "cancelled" ] }, "initiatedByUserId": { "nullable": true, "type": "string" }, "chatConversationId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runtimeTaskId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "nullable": true, "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "error": { "nullable": true, "type": "string" }, "blockedBy": { "nullable": true, "type": "object", "properties": { "phase": { "type": "string", "enum": [ "starting", "running", "stopping" ] }, "runId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runtimeTaskId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "elapsedSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deadline": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "maximumDurationSeconds": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "phase", "runId", "runtimeTaskId", "startedAt", "elapsedSeconds", "deadline", "maximumDurationSeconds" ], "additionalProperties": false }, "artifact": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "triggerId", "runKind", "status", "initiatedByUserId", "chatConversationId", "runtimeTaskId", "startedAt", "completedAt", "error", "blockedBy", "artifact", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/schedule-triggers/{id}/runs/{runId}": { "get": { "operationId": "getScheduleTriggerRun", "tags": [ "Schedule Triggers" ], "description": "Get a single run for a scheduled agent trigger\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:read`](/docs/reference/permissions#project:read): View projects, their schedules, and your own sessions inside them", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "triggerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runKind": { "type": "string", "enum": [ "due", "manual" ] }, "status": { "type": "string", "enum": [ "running", "success", "failed", "cancelled" ] }, "initiatedByUserId": { "nullable": true, "type": "string" }, "chatConversationId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runtimeTaskId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "nullable": true, "type": "string", "format": "date-time" }, "completedAt": { "nullable": true, "type": "string", "format": "date-time" }, "error": { "nullable": true, "type": "string" }, "blockedBy": { "nullable": true, "type": "object", "properties": { "phase": { "type": "string", "enum": [ "starting", "running", "stopping" ] }, "runId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runtimeTaskId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "elapsedSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deadline": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "maximumDurationSeconds": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "phase", "runId", "runtimeTaskId", "startedAt", "elapsedSeconds", "deadline", "maximumDurationSeconds" ], "additionalProperties": false }, "artifact": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "triggerId", "runKind", "status", "initiatedByUserId", "chatConversationId", "runtimeTaskId", "startedAt", "completedAt", "error", "blockedBy", "artifact", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:read" ] } } }, "/api/schedule-triggers/{id}/runs/{runId}/conversation": { "post": { "operationId": "createScheduleTriggerRunConversation", "tags": [ "Schedule Triggers" ], "description": "Create or return the chat conversation linked to a schedule run\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`project:create`](/docs/reference/permissions#project:create): Create projects and schedules, and trigger schedule runs", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "agentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chatApiKeyId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "nullable": true, "type": "string" }, "selectedModel": { "type": "string" }, "selectedProvider": { "nullable": true, "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "modelId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "modelPoolId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "autoRouterId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "thinkingEffort": { "nullable": true, "type": "string", "enum": [ "low", "medium", "high" ] }, "hasCustomToolSelection": { "type": "boolean" }, "hooksDebugEnabled": { "type": "boolean" }, "todoList": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "artifact": { "nullable": true, "type": "string" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "origin": { "type": "string", "enum": [ "user", "schedule_trigger", "app_open" ] }, "titleIsPlaceholder": { "type": "boolean" }, "encryptedChat": { "type": "boolean" }, "pinnedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "contentLocked": { "type": "boolean" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "systemPrompt": { "nullable": true, "type": "string" }, "agentType": { "type": "string", "enum": [ "profile", "mcp_gateway", "llm_proxy", "agent" ] }, "toolExposureMode": { "type": "string", "enum": [ "full", "search_and_run_only" ] }, "llmApiKeyId": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "agentType", "toolExposureMode", "llmApiKeyId" ], "additionalProperties": false }, "share": { "nullable": true, "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "organization", "team", "user" ] } }, "required": [ "visibility" ], "additionalProperties": false }, "projectName": { "nullable": true, "type": "string" }, "projectIcon": { "nullable": true, "type": "string" }, "unread": { "type": "boolean" }, "messages": { "type": "array", "items": {} }, "olderMessageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "chatErrors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limit", "usage_limit_exceeded", "authentication", "permission_denied", "invalid_request", "provider_insufficient_balance", "not_found", "context_too_long", "request_too_large", "request_exceeds_rate_limit", "content_filtered", "server_error", "network_error", "empty_response", "incomplete_tool_call", "tool_call_output_truncated", "upstream_stalled", "incomplete_response", "provider_auth_required", "tools_unsupported", "aborted", "unknown" ] }, "message": { "type": "string" }, "isRetryable": { "type": "boolean" }, "sessionId": { "type": "string" }, "traceId": { "type": "string" }, "spanId": { "type": "string" }, "usageLimitExceeded": { "type": "boolean" }, "usageLimitEntityType": { "type": "string" }, "authAction": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerLabel": { "type": "string" } }, "required": [ "provider", "providerLabel" ], "additionalProperties": false }, "subagent": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "originalError": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "status": { "type": "number" }, "message": { "type": "string" }, "type": { "type": "string" }, "raw": {} }, "additionalProperties": false } }, "required": [ "code", "message", "isRetryable" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "error", "createdAt" ], "additionalProperties": false } }, "compactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "summary": { "type": "string" }, "compactedThroughMessageId": { "nullable": true, "type": "string" }, "trigger": { "type": "string", "enum": [ "auto", "manual" ] }, "provider": { "type": "string" }, "model": { "type": "string" }, "originalTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "compactedTokenEstimate": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "conversationId", "summary", "compactedThroughMessageId", "trigger", "provider", "model", "originalTokenEstimate", "compactedTokenEstimate", "createdAt" ], "additionalProperties": false } }, "contextTokensUsed": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "userId", "organizationId", "agentId", "chatApiKeyId", "title", "selectedModel", "selectedProvider", "modelId", "modelPoolId", "autoRouterId", "thinkingEffort", "hasCustomToolSelection", "hooksDebugEnabled", "todoList", "artifact", "projectId", "origin", "titleIsPlaceholder", "encryptedChat", "pinnedAt", "lastMessageAt", "createdAt", "updatedAt", "deletedAt", "agent", "share", "messages", "chatErrors", "compactions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "project:create" ] } } }, "/api/secrets/type": { "get": { "operationId": "getSecretsType", "tags": [ "Secrets" ], "description": "Get the secrets manager type and configuration details (for Vault)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DB", "Vault" ] }, "meta": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "type", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/secrets/check-connectivity": { "post": { "operationId": "checkSecretsConnectivity", "tags": [ "Secrets" ], "description": "Check connectivity to the secrets storage and return secret count.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secretCount": { "type": "number" } }, "required": [ "secretCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/service-accounts/labels/keys": { "get": { "operationId": "serviceAccountLabelKeys", "tags": [ "Service Accounts" ], "description": "Get all label keys used by service accounts\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`serviceAccount:read`](/docs/reference/permissions#serviceAccount:read): Open Service Accounts", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "serviceAccount:read" ] } } }, "/api/service-accounts/labels/values": { "get": { "operationId": "serviceAccountLabelValues", "tags": [ "Service Accounts" ], "description": "Get all label values used by service accounts\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`serviceAccount:read`](/docs/reference/permissions#serviceAccount:read): Open Service Accounts", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "serviceAccount:read" ] } } }, "/api/service-accounts": { "get": { "operationId": "getServiceAccounts", "tags": [ "Service Accounts" ], "description": "List organization service accounts\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "role": { "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "disabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "tokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeTokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "soonestExpiryAt": { "nullable": true, "type": "string", "format": "date-time" }, "federatedCredentialCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "createdBy", "organizationId", "name", "description", "icon", "role", "teamId", "disabled", "createdAt", "updatedAt", "labels", "tokenCount", "activeTokenCount", "lastUsedAt", "soonestExpiryAt", "federatedCredentialCount" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createServiceAccount", "tags": [ "Service Accounts" ], "description": "Create an organization service account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`serviceAccount:create`](/docs/reference/permissions#serviceAccount:create): Create service accounts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "nullable": true, "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string" }, "role": { "type": "string", "minLength": 1, "maxLength": 256 }, "teamId": { "nullable": true, "type": "string", "minLength": 1 }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name", "role" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "role": { "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "disabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "tokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeTokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "soonestExpiryAt": { "nullable": true, "type": "string", "format": "date-time" }, "federatedCredentialCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "disabled": { "type": "boolean" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "tokenStart", "disabled", "lastUsedAt", "expiresAt", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "createdBy", "organizationId", "name", "description", "icon", "role", "teamId", "disabled", "createdAt", "updatedAt", "labels", "tokenCount", "activeTokenCount", "lastUsedAt", "soonestExpiryAt", "federatedCredentialCount", "tokens" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "serviceAccount:create" ] } } }, "/api/service-accounts/{id}": { "get": { "operationId": "getServiceAccount", "tags": [ "Service Accounts" ], "description": "Get one organization service account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "role": { "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "disabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "tokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeTokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "soonestExpiryAt": { "nullable": true, "type": "string", "format": "date-time" }, "federatedCredentialCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "disabled": { "type": "boolean" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "tokenStart", "disabled", "lastUsedAt", "expiresAt", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "createdBy", "organizationId", "name", "description", "icon", "role", "teamId", "disabled", "createdAt", "updatedAt", "labels", "tokenCount", "activeTokenCount", "lastUsedAt", "soonestExpiryAt", "federatedCredentialCount", "tokens" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateServiceAccount", "tags": [ "Service Accounts" ], "description": "Update an organization service account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "nullable": true, "type": "string", "maxLength": 1000 }, "icon": { "nullable": true, "type": "string" }, "role": { "type": "string", "minLength": 1, "maxLength": 256 }, "teamId": { "nullable": true, "type": "string", "minLength": 1 }, "disabled": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "organizationId": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "icon": { "nullable": true, "type": "string" }, "role": { "type": "string" }, "teamId": { "nullable": true, "type": "string" }, "disabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "tokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeTokenCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "soonestExpiryAt": { "nullable": true, "type": "string", "format": "date-time" }, "federatedCredentialCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "disabled": { "type": "boolean" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "tokenStart", "disabled", "lastUsedAt", "expiresAt", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "createdBy", "organizationId", "name", "description", "icon", "role", "teamId", "disabled", "createdAt", "updatedAt", "labels", "tokenCount", "activeTokenCount", "lastUsedAt", "soonestExpiryAt", "federatedCredentialCount", "tokens" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteServiceAccount", "tags": [ "Service Accounts" ], "description": "Delete an organization service account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/service-accounts/bulk": { "patch": { "operationId": "bulkSetServiceAccountsDisabled", "tags": [ "Service Accounts" ], "description": "Enable or disable several service accounts in one request. A disabled account authenticates with none of its keys, so this is the reversible way to stop an automation without destroying the keys it would need to start again. Ids outside the caller's organization are reported in `failed` as not found and leave the rest of the batch applied. An account already in the requested state is reported as succeeded without being rewritten.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." }, "disabled": { "type": "boolean" } }, "required": [ "ids", "disabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "bulkDeleteServiceAccounts", "tags": [ "Service Accounts" ], "description": "Delete several service accounts in one request, along with their tokens. Ids outside the caller's organization are reported in `failed` as not found and leave the rest of the batch applied.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/service-accounts/{id}/tokens": { "post": { "operationId": "createServiceAccountToken", "tags": [ "Service Accounts" ], "description": "Create a token for an organization service account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "expiresIn": { "nullable": true, "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "name" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "disabled": { "type": "boolean" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "token": { "type": "string" } }, "required": [ "id", "name", "tokenStart", "disabled", "lastUsedAt", "expiresAt", "createdAt", "token" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/service-accounts/{id}/tokens/{tokenId}": { "delete": { "operationId": "deleteServiceAccountToken", "tags": [ "Service Accounts" ], "description": "Delete one service account token\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tokenId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateServiceAccountToken", "tags": [ "Service Accounts" ], "description": "Update one service account token\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "expiresAt": { "nullable": true }, "disabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tokenId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "disabled": { "type": "boolean" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "tokenStart", "disabled", "lastUsedAt", "expiresAt", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/sessions/bulk": { "delete": { "operationId": "bulkRevokeSessions", "tags": [ "Sessions" ], "description": "Revoke several non-current sessions belonging to the authenticated user in one request. Sessions belonging to another user and the current session are reported in `failed`; the rest are revoked.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Session ids to revoke. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/site-notification": { "get": { "operationId": "getSiteNotification", "tags": [ "Site Notification" ], "description": "Get the active site notification for the current organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "expiresAt": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" }, "isActive": { "type": "boolean" }, "dismissible": { "type": "boolean" } }, "required": [ "id", "content", "expiresAt", "createdAt", "isActive", "dismissible" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createSiteNotification", "tags": [ "Site Notification" ], "description": "Replace the organization site notification, optionally keeping it inactive.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "isActive": { "type": "boolean" }, "dismissible": { "type": "boolean" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "expiresAt": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" }, "isActive": { "type": "boolean" }, "dismissible": { "type": "boolean" } }, "required": [ "id", "content", "expiresAt", "createdAt", "isActive", "dismissible" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/site-notification/settings": { "get": { "operationId": "getSiteNotificationSettings", "tags": [ "Site Notification" ], "description": "Get the latest site notification for settings management\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:read`](/docs/reference/permissions#organizationSettings:read): View every organization settings page, including messaging channels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "expiresAt": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" }, "isActive": { "type": "boolean" }, "dismissible": { "type": "boolean" } }, "required": [ "id", "content", "expiresAt", "createdAt", "isActive", "dismissible" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:read" ] } } }, "/api/site-notification/{id}": { "put": { "operationId": "updateSiteNotification", "tags": [ "Site Notification" ], "description": "Update an existing site notification\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "isActive": { "type": "boolean" }, "dismissible": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "expiresAt": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" }, "isActive": { "type": "boolean" }, "dismissible": { "type": "boolean" } }, "required": [ "id", "content", "expiresAt", "createdAt", "isActive", "dismissible" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } }, "delete": { "operationId": "deleteSiteNotification", "tags": [ "Site Notification" ], "description": "Delete a site notification\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/skill-marketplace": { "get": { "operationId": "getSkillMarketplace", "tags": [ "Skills" ], "description": "The static skill marketplace: one clone URL for the whole deployment, which every user installs with their own credential.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cloneUrl": { "type": "string" }, "marketplaceName": { "type": "string" }, "requiresAuthentication": { "type": "boolean" } }, "required": [ "cloneUrl", "marketplaceName", "requiresAuthentication" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/{id}/transfer-ownership": { "post": { "operationId": "transferSkillOwnership", "tags": [ "Ownership" ], "description": "Transfer ownership to another organization member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "minLength": 1 } }, "required": [ "ownerId" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/labels/keys": { "get": { "operationId": "skillLabelKeys", "tags": [ "Skills" ], "description": "Get all label keys used by skills\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/labels/values": { "get": { "operationId": "skillLabelValues", "tags": [ "Skills" ], "description": "Get all label values used by skills\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills": { "get": { "operationId": "getSkills", "tags": [ "Skills" ], "description": "List all agent skills for the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeContent", "required": false, "description": "Include manifest bodies (default true). False returns empty content for lightweight lists." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "visibleTo", "required": false, "description": "Admin-only: list skills visible to this user in the current organization, using the target user's permissions." }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sourceRepo", "required": false }, { "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "in": "query", "name": "skillIds", "required": false, "description": "Restrict results to these skill IDs (comma-separated)." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "forAgentId", "required": false, "description": "Restrict results to native skills available through this internal agent or eligible for publication by this saved MCP gateway." }, { "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "enum": [ "default" ] } ] }, "in": "query", "name": "mcpGatewayEnvironment", "required": false, "description": "Preview skills eligible for MCP Gateway All mode using this form environment. Use `default` for the Default environment." }, { "schema": { "default": "effective", "type": "string", "enum": [ "effective", "eligible" ] }, "in": "query", "name": "agentSkillView", "required": false, "description": "Effective applies the saved skill policy. Eligible previews the skills that All mode can include before its exclusions." }, { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": false, "description": "Filter by visibility scope: personal, team, or org." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "teamIds", "required": false, "description": "Team IDs (comma-separated); only used when scope=team." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "authorIds", "required": false, "description": "Author user IDs (comma-separated). Admin-only; used with scope=personal." }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "excludeAuthorIds", "required": false, "description": "Exclude author user IDs (comma-separated). Admin-only; used with scope=personal." }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeOtherPersonalSkills", "required": false, "description": "Hide personal skills owned by other users. Admin-only; no-op for non-admins." }, { "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted" ] }, "in": "query", "name": "status", "required": false, "description": "Which skills to list: active (default) or the soft-deleted trash. `deleted` is restricted to callers who manage every skill." }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." }, { "schema": { "type": "string", "enum": [ "usageCount", "lastUsedAt", "name", "createdAt" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "canPublish": { "type": "boolean" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "fileCount": { "type": "number" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "usageUserCount": { "type": "number" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "createdBy", "fileCount", "teams", "users", "environments", "authorName", "usageUserCount", "labels" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createSkill", "tags": [ "Skills" ], "description": "Create a skill from a raw SKILL.md and resource files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:create`](/docs/reference/permissions#skill:create): Create new agent skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10485760, "description": "A complete SKILL.md manifest: a YAML frontmatter block with `name` and `description` (and optional `license`, `compatibility`, `allowed-tools`, `agent`, `templated`, `metadata`), followed by the Markdown instruction body. Set `templated: true` to render the body through Handlebars (e.g. `{{user.name}}`) at activation. `allowed-tools` is a space-separated list of tools the skill is pre-approved to use. `agent` names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context." }, "icon": { "description": "Emoji or base64 image data URL shown with the name. Omit to leave it untouched; null clears it.", "nullable": true, "type": "string" }, "files": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Resource path, e.g. references/API.md or scripts/run.py" }, "content": { "type": "string", "maxLength": 13981016, "description": "Text content of the file" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] } }, "required": [ "path", "content" ] } }, "environmentIds": { "description": "Environments the skill is restricted to. Empty (or omitted on create) makes the skill available to agents in every environment; otherwise only agents in one of the listed environments see it.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "allowedTools": { "description": "Tools the skill expects, overriding the SKILL.md `allowed-tools` frontmatter. Omit to use the frontmatter; pass [] to clear.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "content" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "digest": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "path", "content", "encoding", "digest", "kind", "createdAt" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "files", "createdBy", "teams", "users", "environments", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:create" ] } } }, "/api/skills/{id}": { "get": { "operationId": "getSkill", "tags": [ "Skills" ], "description": "Get a skill with its resource files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "digest": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "path", "content", "encoding", "digest", "kind", "createdAt" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "files", "createdBy", "teams", "users", "environments", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateSkill", "tags": [ "Skills" ], "description": "Update a skill's SKILL.md, resource files, and scope\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10485760, "description": "A complete SKILL.md manifest: a YAML frontmatter block with `name` and `description` (and optional `license`, `compatibility`, `allowed-tools`, `agent`, `templated`, `metadata`), followed by the Markdown instruction body. Set `templated: true` to render the body through Handlebars (e.g. `{{user.name}}`) at activation. `allowed-tools` is a space-separated list of tools the skill is pre-approved to use. `agent` names an agent the skill runs in — when set, activating the skill delegates it to that agent instead of loading the instructions into the caller's context." }, "icon": { "description": "Emoji or base64 image data URL shown with the name. Omit to leave it untouched; null clears it.", "nullable": true, "type": "string" }, "files": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Resource path, e.g. references/API.md or scripts/run.py" }, "content": { "type": "string", "maxLength": 13981016, "description": "Text content of the file" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] } }, "required": [ "path", "content" ] } }, "environmentIds": { "description": "Environments the skill is restricted to. Empty (or omitted on create) makes the skill available to agents in every environment; otherwise only agents in one of the listed environments see it.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "allowedTools": { "description": "Tools the skill expects, overriding the SKILL.md `allowed-tools` frontmatter. Omit to use the frontmatter; pass [] to clear.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Key/value labels. Omit to leave existing labels untouched; pass [] to clear them.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "baseVersion": { "description": "The skill's `latestVersion` when this edit was composed. Rejected with 409 if the skill has moved past it. Omit only when the payload owes nothing to a prior read of the skill.", "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "digest": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "path", "content", "encoding", "digest", "kind", "createdAt" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "files", "createdBy", "teams", "users", "environments", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteSkill", "tags": [ "Skills" ], "description": "Delete a skill and its resource files\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/{id}/usage-statistics": { "get": { "operationId": "getSkillUsageStatistics", "tags": [ "Skills" ], "description": "Per-user activation counts for a skill over the last 30 days\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string" }, "users": { "type": "array", "items": { "type": "object", "properties": { "userId": { "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "user", "service_account", "unattributed" ] }, "total": { "type": "number" } }, "required": [ "userId", "name", "kind", "total" ], "additionalProperties": false } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "userId": { "nullable": true, "type": "string" }, "count": { "type": "number" } }, "required": [ "date", "userId", "count" ], "additionalProperties": false } } }, "required": [ "since", "users", "daily" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/{id}/versions": { "get": { "operationId": "getSkillVersions", "tags": [ "Skills" ], "description": "List a skill's version history, newest first, as metadata only (no SKILL.md body). Version numbers are contiguous from 1. Paginated.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "contentHash": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "version", "contentHash", "sourceCommit", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/{id}/versions/{version}": { "get": { "operationId": "getSkillVersion", "tags": [ "Skills" ], "description": "Get one immutable skill version: the SKILL.md body it captured plus its resource-file snapshots.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "content": { "type": "string" }, "contentHash": { "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "versionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "versionId", "path", "content", "encoding", "kind", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "skillId", "version", "content", "contentHash", "sourceCommit", "createdAt", "files" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/names": { "get": { "operationId": "getSkillNames", "tags": [ "Skills" ], "description": "List the ids and names of the skills the caller can read, in the default list order, with their total. A lightweight alternative to paging the full list for pickers and setups that name or send every visible skill.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "default": 1111, "type": "integer", "minimum": 1, "maximum": 1111 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "data", "total" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/source-repos": { "get": { "operationId": "getSkillSourceRepos", "tags": [ "Skills" ], "description": "List distinct GitHub and GitLab repositories that skills in this organization were imported from\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repos": { "type": "array", "items": { "type": "string" } } }, "required": [ "repos" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/bulk-delete": { "post": { "operationId": "bulkDeleteSkills", "tags": [ "Skills" ], "description": "Soft-delete several skills in one request. Each id is authorized exactly as the single-skill delete authorizes its own: an id the caller cannot see or modify is reported in `failed` and the rest of the batch still applies. Deleted skills keep their versions and resource files and can be restored from the trash.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skillIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Skills to act on. Duplicates are collapsed." } }, "required": [ "skillIds" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/{id}/restore": { "post": { "operationId": "restoreSkill", "tags": [ "Skills" ], "description": "Restore a soft-deleted skill\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "digest": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "path", "content", "encoding", "digest", "kind", "createdAt" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "files", "createdBy", "teams", "users", "environments", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/{id}/permanent": { "delete": { "operationId": "permanentlyDeleteSkill", "tags": [ "Skills" ], "description": "Permanently destroy a soft-deleted skill (global admins only). Irreversible, with no grace period: every version and resource file is destroyed, along with the skill's team and user grants, environment assignments, usage events, and share links — so any public share URL for it stops working. 404 if there is no soft-deleted skill with that id in the org, which is also the answer when the skill is still live or the caller is not a global admin. 409 while a sandbox still has the skill mounted; that is retryable, but note nothing clears a mount on its own — it lasts as long as the sandbox does. Built-in skills cannot be purged: their soft-deleted row is what stops the seeder recreating them on the next restart. Restore wins a race.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRestricted to the built-in Admin and Platform Admin roles. No permission grants it: [`skill:delete`](/docs/reference/permissions#skill:delete) and even `skill:admin` reach the trash, not past it, and a service account never qualifies. A caller without it gets 404, not 403, so the endpoint never confirms the skill exists.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Restricted to the built-in Admin and Platform Admin roles. No permission grants it: `skill:delete` and even `skill:admin` reach the trash, not past it, and a service account never qualifies. A caller without it gets 404, not 403, so the endpoint never confirms the skill exists.", "permissions": [] } } }, "/api/skills/{id}/reset": { "post": { "operationId": "resetSkill", "tags": [ "Skills" ], "description": "Reset a built-in skill to its shipped default SKILL.md and resource files. Only applies to skills with sourceType `built_in`.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "digest": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "path", "content", "encoding", "digest", "kind", "createdAt" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "files", "createdBy", "teams", "users", "environments", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/{id}/github-sync": { "patch": { "operationId": "updateSkillGithubSync", "tags": [ "Skills" ], "description": "Manage a Git-synced skill: change its pull frequency or its source (repository, branch, folder, credential), trigger an immediate pull, or disconnect it from the Git source (interval null) — a disconnected skill keeps its content and provenance and becomes editable in the app. Providing a full source reconnects a previously imported skill after verifying the repository.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interval": { "description": "New pull frequency.", "type": "string", "enum": [ "15m", "1h", "1d" ] }, "source": { "description": "Pull the skill from another repository, branch, folder, or credential. It is fetched before anything changes, so a location without the skill is refused.", "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string" }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillPath": { "type": "string", "description": "The skill's folder from the repository root; empty when the skill is the repository." } }, "required": [ "repoUrl", "skillPath" ], "additionalProperties": false }, "syncNow": { "description": "Trigger an immediate pull from the source repo.", "type": "boolean", "enum": [ true ] }, "disconnect": { "description": "Disconnect the skill from its GitHub source: it keeps its content and becomes editable in the app.", "type": "boolean", "enum": [ true ] } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "digest": { "nullable": true, "type": "string" }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "skillId", "path", "content", "encoding", "digest", "kind", "createdAt" ], "additionalProperties": false } }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false } }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt", "files", "createdBy", "teams", "users", "environments", "labels" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skills/enable-defaults": { "post": { "operationId": "enableSkillToolDefaults", "tags": [ "Skills" ], "description": "Enable the Agent Skill tools (`list_skills`, `load_skill`) for this organization. Sets the org-level flag and backfills the tools onto every existing agent. Idempotent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`organizationSettings:update`](/docs/reference/permissions#organizationSettings:update): Change organization settings, messaging channels, and site notifications", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "enum": [ true ] }, "agentsBackfilled": { "type": "number" } }, "required": [ "enabled", "agentsBackfilled" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "organizationSettings:update" ] } } }, "/api/skills/catalog/search": { "get": { "operationId": "searchSkillCatalog", "tags": [ "Skills" ], "description": "Search the crawled public-GitHub skill catalog by name, repo, path, or description. Backed by an in-memory token index; returns ranked candidates to import via the GitHub import endpoints.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "default": "", "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "repo": { "type": "string" }, "skillPath": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "fileCount": { "type": "number" } }, "required": [ "repo", "skillPath", "name", "description", "compatibility", "fileCount" ], "additionalProperties": false } }, "totalCount": { "type": "number" } }, "required": [ "results", "totalCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/github/discover": { "post": { "operationId": "discoverGithubSkills", "tags": [ "Skills" ], "description": "Discover skills in a GitHub or GitLab repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string" }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "repoUrl" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string" }, "ref": { "type": "string" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "skillPath": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "fileCount": { "type": "number" }, "exists": { "type": "boolean" } }, "required": [ "skillPath", "name", "description", "compatibility", "allowedTools", "templated", "fileCount", "exists" ], "additionalProperties": false } } }, "required": [ "repoUrl", "ref", "skills" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/github/preview": { "post": { "operationId": "previewGithubSkill", "tags": [ "Skills" ], "description": "Fetch a single skill's manifest and files from GitHub or GitLab without persisting it.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string" }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillPath": { "type": "string" } }, "required": [ "repoUrl", "skillPath" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "content": { "type": "string" }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "kind": { "type": "string", "enum": [ "reference", "script", "asset" ] } }, "required": [ "path", "content", "encoding", "kind" ], "additionalProperties": false } }, "skippedFiles": { "type": "array", "items": { "type": "string" }, "description": "Resource paths not imported: oversized, beyond the per-skill file cap, or unfetchable" }, "sourceRef": { "type": "string" }, "sourceCommit": { "type": "string" } }, "required": [ "name", "description", "content", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "files", "skippedFiles", "sourceRef", "sourceCommit" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:read" ] } } }, "/api/skills/github/import": { "post": { "operationId": "importGithubSkills", "tags": [ "Skills" ], "description": "Import selected skills from a GitHub or GitLab repository\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`skill:create`](/docs/reference/permissions#skill:create): Create new agent skills", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "provider": { "description": "Git host of a public repository; defaults to github. Ignored when a credential is given.", "type": "string", "enum": [ "github", "gitlab" ] }, "githubToken": { "type": "string" }, "githubAppConfigId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "gitlabTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skillPaths": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } }, "sync": { "default": { "interval": "1d" }, "description": "Pull schedule for the imported skills. Every import is synced from the repo and read-only in the app until disconnected. Defaults to daily.", "type": "object", "properties": { "interval": { "type": "string", "enum": [ "15m", "1h", "1d" ] } }, "required": [ "interval" ] } }, "required": [ "repoUrl", "skillPaths" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "authorId": { "nullable": true, "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "nullable": true, "type": "string" }, "content": { "type": "string" }, "digest": { "nullable": true, "type": "string" }, "latestVersion": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "license": { "nullable": true, "type": "string" }, "compatibility": { "nullable": true, "type": "string" }, "allowedTools": { "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "templated": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "sourceType": { "type": "string", "enum": [ "manual", "github", "built_in" ] }, "sourceRef": { "nullable": true, "type": "string" }, "sourceOrigin": { "nullable": true, "type": "string" }, "sourceCommit": { "nullable": true, "type": "string" }, "githubSyncInterval": { "anyOf": [ { "type": "string", "enum": [ "15m", "1h", "1d" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "githubSyncRef": { "nullable": true, "type": "string" }, "githubAppConfigId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "githubPatId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProvider": { "anyOf": [ { "type": "string", "enum": [ "github", "gitlab" ] }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, "gitlabTokenId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastSyncedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastSyncError": { "nullable": true, "type": "string" }, "usageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "organizationId", "authorId", "scope", "name", "description", "icon", "content", "digest", "latestVersion", "license", "compatibility", "allowedTools", "agentName", "templated", "metadata", "sourceType", "sourceRef", "sourceOrigin", "sourceCommit", "githubSyncInterval", "githubSyncRef", "githubAppConfigId", "githubPatId", "sourceProvider", "gitlabTokenId", "lastSyncedAt", "lastSyncError", "usageCount", "lastUsedAt", "createdByServiceAccountId", "createdAt", "updatedAt", "deletedAt" ], "additionalProperties": false } }, "skipped": { "type": "array", "items": { "type": "string" } }, "skippedFiles": { "type": "array", "items": { "type": "object", "properties": { "skillPath": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } } }, "required": [ "skillPath", "files" ], "additionalProperties": false }, "description": "Per created skill, resource paths not imported: oversized, beyond the per-skill file cap, or unfetchable" } }, "required": [ "created", "skipped", "skippedFiles" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "skill:create" ] } } }, "/api/skill-sandbox/artifacts/{artifactId}": { "get": { "operationId": "getSkillSandboxArtifact", "tags": [ "Skills" ], "description": "Stream the raw bytes of a skill sandbox artifact. Inline for known-safe raster images and real PDFs, so the browser can preview them; download for everything else.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "type": "string", "pattern": "^(?:[0-9a-fA-F-]{36}|obj_[A-Za-z0-9_-]{1,2048})$" }, "in": "path", "name": "artifactId", "required": true } ], "responses": { "200": { "description": "Default Response" } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } }, "delete": { "operationId": "deleteSkillSandboxArtifact", "tags": [ "Skills" ], "description": "Delete a persistent file. Allowed for the file's author, or anyone with access to the project owning the file.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "type": "string", "pattern": "^(?:[0-9a-fA-F-]{36}|obj_[A-Za-z0-9_-]{1,2048})$" }, "in": "path", "name": "artifactId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } } }, "/api/skill-sandbox/artifacts/{artifactId}/content": { "put": { "operationId": "updateSkillSandboxArtifactContent", "tags": [ "Skills" ], "description": "Overwrite the full text content of a Markdown/plain-text file. Allowed for the file's author, or anyone with access to the project owning the file.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 1000000 } }, "required": [ "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^(?:[0-9a-fA-F-]{36}|obj_[A-Za-z0-9_-]{1,2048})$" }, "in": "path", "name": "artifactId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "fileId": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "number" } }, "required": [ "ok", "fileId", "filename", "mimeType", "sizeBytes" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } } }, "/api/skill-sandbox/conversations/{conversationId}/artifacts": { "get": { "operationId": "getSkillSandboxConversationArtifacts", "tags": [ "Skills" ], "description": "List the artifact files produced in a conversation's sandbox.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`agent:read`](/docs/reference/permissions#agent:read): Open Agents, and use the code sandboxes and files of agents you can use", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "downloadRef": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time" }, "downloadable": { "type": "boolean" }, "projectId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "nullable": true, "type": "string" } }, "required": [ "id", "downloadRef", "filename", "mimeType", "sizeBytes", "createdAt", "downloadable", "projectId", "projectName" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "agent:read" ] } } }, "/api/skill-share-links": { "get": { "operationId": "getSkillShareLinks", "tags": [ "Skills" ], "description": "List skill share links for the organization, optionally filtered by skill\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "skillId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "createdByUserId": { "type": "string" }, "tokenStart": { "type": "string", "maxLength": 22 }, "name": { "nullable": true, "type": "string" }, "marketplaceName": { "type": "string" }, "pluginClientType": { "nullable": true, "type": "string" }, "pluginPlatform": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "revokedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "name", "description" ], "additionalProperties": false } }, "plugins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "clientType": { "type": "string" }, "contentHash": { "type": "string" } }, "required": [ "id", "pluginSlug", "displayName", "description", "clientType", "contentHash" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "createdByUserId", "tokenStart", "name", "marketplaceName", "pluginClientType", "pluginPlatform", "expiresAt", "revokedAt", "lastUsedAt", "createdAt", "updatedAt", "status", "skills", "plugins" ], "additionalProperties": false } } }, "required": [ "links" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createSkillShareLink", "tags": [ "Skills" ], "description": "Create a share link exposing one or more skills via the public marketplace endpoint. The raw token is returned exactly once.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skillIds": { "maxItems": 1111, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "pluginIds": { "maxItems": 555, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "pluginPlatform": { "type": "string", "enum": [ "posix", "windows" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "createdByUserId": { "type": "string" }, "tokenStart": { "type": "string", "maxLength": 22 }, "name": { "nullable": true, "type": "string" }, "marketplaceName": { "type": "string" }, "pluginClientType": { "nullable": true, "type": "string" }, "pluginPlatform": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "revokedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "name", "description" ], "additionalProperties": false } }, "plugins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "clientType": { "type": "string" }, "contentHash": { "type": "string" } }, "required": [ "id", "pluginSlug", "displayName", "description", "clientType", "contentHash" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "createdByUserId", "tokenStart", "name", "marketplaceName", "pluginClientType", "pluginPlatform", "expiresAt", "revokedAt", "lastUsedAt", "createdAt", "updatedAt", "status", "skills", "plugins" ], "additionalProperties": false }, "rawToken": { "type": "string" }, "cloneUrl": { "type": "string" }, "marketplaceName": { "type": "string" } }, "required": [ "link", "rawToken", "cloneUrl", "marketplaceName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skill-share-links/{id}/rotate": { "post": { "operationId": "rotateSkillShareLink", "tags": [ "Skills" ], "description": "Rotate a share link: revoke it and create its replacement in one transaction, so no failure mode leaves both tokens live. The new raw token is returned exactly once.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skillIds": { "maxItems": 1111, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "pluginIds": { "maxItems": 555, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "pluginPlatform": { "type": "string", "enum": [ "posix", "windows" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "createdByUserId": { "type": "string" }, "tokenStart": { "type": "string", "maxLength": 22 }, "name": { "nullable": true, "type": "string" }, "marketplaceName": { "type": "string" }, "pluginClientType": { "nullable": true, "type": "string" }, "pluginPlatform": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "revokedAt": { "nullable": true, "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "name", "description" ], "additionalProperties": false } }, "plugins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "pluginSlug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "clientType": { "type": "string" }, "contentHash": { "type": "string" } }, "required": [ "id", "pluginSlug", "displayName", "description", "clientType", "contentHash" ], "additionalProperties": false } } }, "required": [ "id", "organizationId", "createdByUserId", "tokenStart", "name", "marketplaceName", "pluginClientType", "pluginPlatform", "expiresAt", "revokedAt", "lastUsedAt", "createdAt", "updatedAt", "status", "skills", "plugins" ], "additionalProperties": false }, "rawToken": { "type": "string" }, "cloneUrl": { "type": "string" }, "marketplaceName": { "type": "string" } }, "required": [ "link", "rawToken", "cloneUrl", "marketplaceName" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/skill-share-links/{id}": { "delete": { "operationId": "revokeSkillShareLink", "tags": [ "Skills" ], "description": "Revoke a skill share link. Idempotent: revoking an already-revoked link is a no-op.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/statistics/llm-proxy": { "get": { "operationId": "getProxyCostStatistics", "tags": [ "Statistics" ], "description": "LLM Proxy usage by authentication method and credential, including legacy proxy profiles. Each request is counted once. Billed spend excludes subscription-covered list-price estimates. Credential details are paginated; totals and time series cover the entire filtered result. Null credential IDs mean unavailable or not applicable; provider secrets are never returned. Callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage. With labelKey, also return separately paginated label groups. Labels are captured at request admission: authenticated virtual-key or OAuth-client labels override labels on its billing team. Caller metadata cannot override these labels. Label edits and deletions do not rewrite history; requests without a snapshot value form the null/unassigned group. All totals, trends and groupings apply the same label filters. With includeProviderKeys or includeModelPools, also return usage grouped by the provider key that served each call or the model pool it went through; null groups are calls with no recorded key or no pool. A request a model pool failed over writes one row per attempt: failed attempts count as requests at zero cost and tokens, and failedOverAttempts counts them.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "serviceAccountId", "required": false, "description": "Limit spend to this authenticated service-account principal across its OAuth clients and virtual keys." }, { "schema": { "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "in": "query", "name": "authMethod", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "in": "query", "name": "credentialId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "providerApiKeyId", "required": false, "description": "Limit usage to calls served by this provider key." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "modelPoolId", "required": false, "description": "Limit usage to calls balanced through this model pool." }, { "schema": { "type": "string" }, "in": "query", "name": "includeProviderKeys", "required": false, "description": "Also group usage by the provider key that served each call." }, { "schema": { "type": "string" }, "in": "query", "name": "includeModelPools", "required": false, "description": "Also group usage by the model pool each call went through." }, { "schema": { "type": "string" }, "in": "query", "name": "includeLabelKeys", "required": false, "description": "Include the distinct historical label keys in the filtered proxy usage." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "in": "query", "name": "labelKey", "required": false, "description": "Group by the admission-time value of this server-owned label." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "query", "name": "labelValue", "required": false, "description": "Match this exact historical label value. Requires labelKey; cannot be combined with labelUnassigned=true." }, { "schema": { "type": "string" }, "in": "query", "name": "labelUnassigned", "required": false, "description": "Match requests without a snapshot value for labelKey, including older requests. Requires labelKey." }, { "schema": { "type": "string" }, "in": "query", "name": "includeGroupTimeSeries", "required": false, "description": "Also return a time series on every returned group: each method, credential, provider key, model pool and label value on the current page." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts" ], "additionalProperties": false }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timestamp": { "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "timestamp" ], "additionalProperties": false } }, "methods": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timestamp": { "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "timestamp" ], "additionalProperties": false } }, "authMethod": { "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "authMethod" ], "additionalProperties": false } }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timestamp": { "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "timestamp" ], "additionalProperties": false } }, "authMethod": { "type": "string", "enum": [ "provider_key", "virtual_key", "passthrough_virtual_key", "jwks", "oauth_client_credentials", "oauth_user", "personal_token", "internal", "unknown" ] }, "credentialId": { "nullable": true, "type": "string" }, "credentialName": { "nullable": true, "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "authMethod", "credentialId", "credentialName" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "number" }, "offset": { "type": "number" }, "total": { "type": "number" } }, "required": [ "limit", "offset", "total" ], "additionalProperties": false }, "providerKeys": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timestamp": { "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "timestamp" ], "additionalProperties": false } }, "providerApiKeyId": { "nullable": true, "type": "string" }, "providerApiKeyName": { "nullable": true, "type": "string" }, "provider": { "nullable": true, "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "providerApiKeyId", "providerApiKeyName", "provider" ], "additionalProperties": false } }, "modelPools": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timestamp": { "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "timestamp" ], "additionalProperties": false } }, "modelPoolId": { "nullable": true, "type": "string" }, "modelPoolName": { "nullable": true, "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "modelPoolId", "modelPoolName" ], "additionalProperties": false } }, "labelKeys": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "object", "properties": { "key": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "failedOverAttempts": { "type": "number", "description": "Model pool attempts that failed before the provider answered and moved on to the next member. Each is counted in requests at zero cost and tokens." }, "timestamp": { "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "timestamp" ], "additionalProperties": false } }, "value": { "nullable": true, "type": "string" } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "failedOverAttempts", "value" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "number" }, "offset": { "type": "number" }, "total": { "type": "number" } }, "required": [ "limit", "offset", "total" ], "additionalProperties": false } }, "required": [ "key", "groups", "pagination" ], "additionalProperties": false } }, "required": [ "totals", "timeSeries", "methods", "credentials", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/teams": { "get": { "operationId": "getTeamStatistics", "tags": [ "Statistics" ], "description": "Get usage statistics for every team in the active organization. A caller without [`llmCost:read`](/docs/reference/permissions#llmCost:read) who administers a team gets only the teams they administer and their sub-teams; each request then counts for the teams whose spend limits it charges. Filtering by `teamId` does the same for one team.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmCost:read`](/docs/reference/permissions#llmCost:read) for every team in the active organization. A session-authenticated team admin without it receives only the teams they administer and their sub-teams; any other caller gets 403, and so does a team admin filtering by another team.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "teamId", "required": false, "description": "Only requests charged to this team: those billed to it or a sub-team, and those its members made through agents shared with it." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "teamId": { "type": "string" }, "teamName": { "type": "string" }, "members": { "type": "number" }, "agents": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cost": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "teamId", "teamName", "members", "agents", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "cost", "timeSeries" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmCost:read` for every team in the active organization. A session-authenticated team admin without it receives only the teams they administer and their sub-teams; any other caller gets 403, and so does a team admin filtering by another team.", "permissions": [] } } }, "/api/statistics/agents": { "get": { "operationId": "getAgentStatistics", "tags": [ "Statistics" ], "description": "Get usage statistics for every agent in the active organization. Callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage of each agent.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n\nReturns aggregate usage for every agent in the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "agentName": { "type": "string" }, "agentType": { "type": "string" }, "teamName": { "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cost": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "agentId", "agentName", "agentType", "teamName", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "cost", "timeSeries" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "Returns aggregate usage for every agent in the active organization.", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/models": { "get": { "operationId": "getModelStatistics", "tags": [ "Statistics" ], "description": "Get model usage statistics for every interaction in the active organization.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n\nReturns aggregate model usage for the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cost": { "type": "number" }, "percentage": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "model", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "cost", "percentage", "timeSeries" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "Returns aggregate model usage for the active organization.", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/users": { "get": { "operationId": "getUserStatistics", "tags": [ "Statistics" ], "description": "Get organization-wide per-user usage statistics (requests, tokens, cost and model mix), for AI-adoption reporting. Paginated because user cardinality is unbounded. Only traffic that carries a resolved user identity is included; requests authenticated with a shared credential and no user context are not attributed to anyone. Callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n\nReturns the caller's usage. [`member:read`](/docs/reference/permissions#member:read) includes identified users across the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "includeTimeSeries", "required": false, "description": "Include a per-user cost time series. Off by default: it multiplies the response by the number of time buckets." }, { "schema": { "type": "string" }, "in": "query", "name": "includeModels", "required": false, "description": "Include each user's per-model usage breakdown. Off by default: it costs an extra aggregation." }, { "schema": { "type": "string" }, "in": "query", "name": "includeModelTimeSeries", "required": false, "description": "Include usage time series for each user's models. Implies includeModels. Off by default: it multiplies the response by models and time buckets." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "totalTokens", "requests", "billedCost", "lastActiveAt", "userName" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "userEmail": { "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "activeDays": { "type": "number" }, "lastActiveAt": { "nullable": true, "type": "string" }, "models": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "percentage": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "model", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "percentage", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "userId", "userName", "userEmail", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "activeDays", "lastActiveAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "Returns the caller's usage. `member:read` includes identified users across the active organization.", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/me": { "get": { "operationId": "getMyStatistics", "tags": [ "Statistics" ], "description": "Get the calling user's own cost and usage for a timeframe: requests, tokens, billed and subscription-covered spend, active days and model mix. Reports only the caller's own activity, so unlike the other statistics endpoints it requires no permission over organization-wide cost data.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "activeDays": { "type": "number" }, "lastActiveAt": { "nullable": true, "type": "string" }, "models": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "percentage": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "model", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "percentage", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost", "activeDays", "lastActiveAt", "models", "timeSeries" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/statistics/me/breakdown": { "get": { "operationId": "getMyUsageBreakdown", "tags": [ "Statistics" ], "description": "Explain the calling user's own usage: the client applications that generated it, the price band their tokens fell into (fresh input, cache read, cache write, output, plus what caching cost and saved), how their requests were distributed across context sizes, and which of their sessions concentrated the spend. Cost here is list price across both billing modes, because this is a consumption view — a caller on a flat-rate plan has no billed spend to apportion. Reports only the caller's own activity, so like `/api/statistics/me` it requires no permission over organization-wide cost data.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokenMix": { "type": "object", "properties": { "freshInputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheCost": { "type": "number" }, "cacheSavings": { "type": "number" } }, "required": [ "freshInputTokens", "cacheReadTokens", "cacheWriteTokens", "outputTokens", "cacheCost", "cacheSavings" ], "additionalProperties": false }, "clients": { "type": "array", "items": { "type": "object", "properties": { "client": { "nullable": true, "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "percentage": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "client", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "percentage", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "contextBuckets": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string", "enum": [ "under32k", "under128k", "under256k", "over256k" ] }, "requests": { "type": "number" }, "tokens": { "type": "number" }, "cost": { "type": "number" } }, "required": [ "bucket", "requests", "tokens", "cost" ], "additionalProperties": false } }, "topSessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string" }, "requests": { "type": "number" }, "tokens": { "type": "number" }, "cost": { "type": "number" }, "billedCost": { "type": "number" }, "startedAt": { "type": "string" }, "lastActiveAt": { "type": "string" }, "durationMinutes": { "type": "number" }, "model": { "nullable": true, "type": "string" }, "client": { "nullable": true, "type": "string" } }, "required": [ "sessionId", "requests", "tokens", "cost", "billedCost", "startedAt", "lastActiveAt", "durationMinutes", "model", "client" ], "additionalProperties": false } }, "totalCost": { "type": "number" }, "unsessionedRequests": { "type": "number" } }, "required": [ "tokenMix", "clients", "contextBuckets", "topSessions", "totalCost", "unsessionedRequests" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/statistics/apps": { "get": { "operationId": "getAppStatistics", "tags": [ "Statistics" ], "description": "Get per-MCP-App cost: what each app cost to build (the LLM spend of the session that authored it) and what it costs to run (its own archestra.llm.complete() calls, plus how often it is opened). Includes an estimated chat-equivalent cost per app, derived from the organization's measured average cost per chat session over the same timeframe — the baseline is returned alongside so the estimate is auditable. Paginated. Apps outside the caller's visibility are excluded.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n\nApp details are limited to apps visible to the caller; `app:admin` includes every app in the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "totalCost", "buildCost", "runtimeCost", "runs", "estimatedNetSavings", "appName" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "appName": { "type": "string" }, "authorName": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" }, "buildRequests": { "type": "number" }, "buildInputTokens": { "type": "number" }, "buildOutputTokens": { "type": "number" }, "buildCost": { "type": "number" }, "buildSessionAppCount": { "type": "number" }, "hasBuildSession": { "type": "boolean" }, "runtimeLlmRequests": { "type": "number" }, "runtimeInputTokens": { "type": "number" }, "runtimeOutputTokens": { "type": "number" }, "runtimeCost": { "type": "number" }, "runs": { "type": "number" }, "toolCalls": { "type": "number" }, "estimatedChatEquivalentCost": { "type": "number" }, "estimatedNetSavings": { "type": "number" } }, "required": [ "appId", "appName", "authorName", "createdAt", "buildRequests", "buildInputTokens", "buildOutputTokens", "buildCost", "buildSessionAppCount", "hasBuildSession", "runtimeLlmRequests", "runtimeInputTokens", "runtimeOutputTokens", "runtimeCost", "runs", "toolCalls", "estimatedChatEquivalentCost", "estimatedNetSavings" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "chatBaselineCostPerSession": { "type": "number" }, "chatBaselineSessions": { "type": "number" } }, "required": [ "data", "pagination", "chatBaselineCostPerSession", "chatBaselineSessions" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "App details are limited to apps visible to the caller; `app:admin` includes every app in the active organization.", "permissions": [ "app:read", "llmCost:read" ] } } }, "/api/statistics/skills": { "get": { "operationId": "getSkillStatistics", "tags": [ "Statistics" ], "description": "Get per-skill cost. `contextTokens` is the skill's own footprint — the tokens its activation blocks added to the model's context, measured when they were injected. The `attributed*` figures are the spend of the turns that then ran with the skill in context, which is shared with everything else in those turns rather than being the skill's bill alone — they are computed for the returned page, so they are not a sortable column. Paginated; skills outside the caller's scope are excluded.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills\n\nSkill details are limited to skills visible to the caller; `skill:admin` includes every skill in the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "enum": [ "contextTokens", "activations", "lastActivatedAt", "skillName" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string" }, "skillName": { "type": "string" }, "activations": { "type": "number" }, "distinctUsers": { "type": "number" }, "contextTokens": { "type": "number" }, "measuredActivations": { "type": "number" }, "attributedSessions": { "type": "number" }, "attributedRequests": { "type": "number" }, "attributedInputTokens": { "type": "number" }, "attributedOutputTokens": { "type": "number" }, "attributedCost": { "type": "number" }, "lastActivatedAt": { "nullable": true, "type": "string" } }, "required": [ "skillId", "skillName", "activations", "distinctUsers", "contextTokens", "measuredActivations", "attributedSessions", "attributedRequests", "attributedInputTokens", "attributedOutputTokens", "attributedCost", "lastActivatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "Skill details are limited to skills visible to the caller; `skill:admin` includes every skill in the active organization.", "permissions": [ "llmCost:read", "skill:read" ] } } }, "/api/statistics/overview": { "get": { "operationId": "getOverviewStatistics", "tags": [ "Statistics" ], "description": "Get organization-wide usage totals and leaders for the active organization. Agent administration permission is not required. Without [`member:read`](/docs/reference/permissions#member:read), the top agent reflects only the caller's own usage, since an agent can be someone's personal one.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n\nReturns aggregate usage for the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalRequests": { "type": "number" }, "totalTokens": { "type": "number" }, "totalCost": { "type": "number" }, "topTeam": { "type": "string" }, "topAgent": { "type": "string" }, "topModel": { "type": "string" } }, "required": [ "totalRequests", "totalTokens", "totalCost", "topTeam", "topAgent", "topModel" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "Returns aggregate usage for the active organization.", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/costs": { "get": { "operationId": "getCostStatistics", "tags": [ "Statistics" ], "description": "Get the Costs overview and model chart from shared aggregates. Active user counts are self-scoped without member:read; no user identities are returned. A caller without [`llmCost:read`](/docs/reference/permissions#llmCost:read) who administers a team gets only the requests charged to the teams they administer and their sub-teams, with active users counted within them. Filtering by `teamId` does the same for one team.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nRequires [`llmCost:read`](/docs/reference/permissions#llmCost:read) for the whole organization. A session-authenticated team admin without it receives only requests charged to the teams they administer and their sub-teams; any other caller gets 403, and so does a team admin filtering by another team.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "teamId", "required": false, "description": "Only requests charged to this team: those billed to it or a sub-team, and those its members made through agents shared with it." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "cost": { "type": "number" }, "percentage": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "value": { "type": "number" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "value" ], "additionalProperties": false } } }, "required": [ "model", "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "cost", "percentage", "timeSeries" ], "additionalProperties": false } }, "costSavings": { "type": "object", "properties": { "totalBaselineCost": { "type": "number" }, "totalActualCost": { "type": "number" }, "totalSavings": { "type": "number" }, "totalSubscriptionCost": { "type": "number" }, "totalCacheSavings": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "baselineCost": { "type": "number" }, "actualCost": { "type": "number" }, "cacheSavings": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "baselineCost", "actualCost", "cacheSavings", "subscriptionCost" ], "additionalProperties": false } } }, "required": [ "totalBaselineCost", "totalActualCost", "totalSavings", "totalSubscriptionCost", "totalCacheSavings", "timeSeries" ], "additionalProperties": false }, "activeUsers": { "type": "number" } }, "required": [ "models", "costSavings", "activeUsers" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "dynamic", "note": "Requires `llmCost:read` for the whole organization. A session-authenticated team admin without it receives only requests charged to the teams they administer and their sub-teams; any other caller gets 403, and so does a team admin filtering by another team.", "permissions": [] } } }, "/api/statistics/cost-savings": { "get": { "operationId": "getCostSavingsStatistics", "tags": [ "Statistics" ], "description": "Get organization-wide cost savings statistics for the active organization. Agent administration permission is not required.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n\nReturns aggregate cost savings for the active organization.", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalBaselineCost": { "type": "number" }, "totalActualCost": { "type": "number" }, "totalSavings": { "type": "number" }, "totalSubscriptionCost": { "type": "number" }, "totalCacheSavings": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "baselineCost": { "type": "number" }, "actualCost": { "type": "number" }, "cacheSavings": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "baselineCost", "actualCost", "cacheSavings", "subscriptionCost" ], "additionalProperties": false } } }, "required": [ "totalBaselineCost", "totalActualCost", "totalSavings", "totalSubscriptionCost", "totalCacheSavings", "timeSeries" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "note": "Returns aggregate cost savings for the active organization.", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/mcp-tool-calls": { "get": { "operationId": "getMcpToolCallUsage", "tags": [ "Statistics" ], "description": "Get MCP tool-call counts grouped by any combination of `day`, `mcpServerName`, `toolName`, `userId`, `agentId` and `appId` — one row per group, with its call and error counts. Group by `day` (UTC calendar days) for a daily series, e.g. `groupBy=day,toolName`. Counts `tools/call` requests made by agents, gateways and apps. Callers without [`member:read`](/docs/reference/permissions#member:read) see only their own calls.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "userId", "required": false, "description": "Only this person's usage." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "teamId", "required": false, "description": "Only usage by direct members of this team." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "day", "mcpServerName", "toolName", "userId", "agentId", "appId" ] } }, "in": "query", "name": "groupBy", "required": false, "description": "Comma-separated dimensions to group by: day, mcpServerName, toolName, userId, agentId, appId. Defaults to mcpServerName,toolName." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "agentId", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "appId", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "mcpServerName", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "toolName", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "UTC calendar day (YYYY-MM-DD). Present when grouped by day." }, "mcpServerName": { "type": "string" }, "toolName": { "description": "Tool name as called, including its server prefix. Null when the name is not readable by the server (encrypted chats).", "nullable": true, "type": "string" }, "userId": { "nullable": true, "description": "Who made the calls. Null for usage without a resolved user. Present when grouped by userId.", "type": "string" }, "userName": { "nullable": true, "type": "string" }, "agentId": { "description": "Agent or gateway that made the calls. Null for app calls.", "nullable": true, "type": "string" }, "agentName": { "nullable": true, "type": "string" }, "appId": { "description": "App that made the calls. Null for agent calls.", "nullable": true, "type": "string" }, "appName": { "nullable": true, "type": "string" }, "calls": { "type": "number" }, "errors": { "type": "number", "description": "Calls whose result was an error." } }, "required": [ "calls", "errors" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "calls": { "type": "number" }, "errors": { "type": "number" } }, "required": [ "calls", "errors" ], "additionalProperties": false } }, "required": [ "data", "pagination", "totals" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/llm-usage": { "get": { "operationId": "getLlmUsage", "tags": [ "Statistics" ], "description": "Get LLM requests, tokens and spend grouped by any combination of `day`, `teamId`, `agentId`, `userId`, `credentialId` (virtual key, passthrough key or OAuth client), `provider` and `model` — one row per group. For example `groupBy=teamId,provider,model` answers which providers and models each team used and what they cost, `groupBy=agentId,userId` who used each agent, and `groupBy=day,credentialId` gives a daily series per virtual key. Each dimension is attributed as on its own statistics endpoint: team as in GET /api/statistics/teams, agent as in GET /api/statistics/agents, credential as in GET /api/statistics/llm-proxy, model as the billed model of GET /api/statistics/models. Grouped by agent, person or credential, or filtered by credential, callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "day", "teamId", "agentId", "userId", "credentialId", "provider", "model" ] } }, "in": "query", "name": "groupBy", "required": false, "description": "Comma-separated dimensions to group by: day, teamId, agentId, userId, credentialId, provider, model. Defaults to teamId,provider,model." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "teamId", "required": false, "description": "Only this team's usage." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "credentialId", "required": false, "description": "Only this virtual key, passthrough key or OAuth client." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "provider", "required": false, "description": "Only this provider, e.g. anthropic." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "model", "required": false, "description": "Only this billed model." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "UTC calendar day (YYYY-MM-DD). Present when grouped by day." }, "teamId": { "description": "Team the usage is attributed to: the credential's billing team, otherwise each team the agent is shared with (the same attribution as GET /api/statistics/teams). Present when grouped by teamId.", "type": "string" }, "teamName": { "type": "string" }, "agentId": { "description": "Agent, MCP gateway or LLM proxy that made the requests, as in GET /api/statistics/agents: legacy proxy rows count under the organization's LLM proxy. Present when grouped by agentId.", "type": "string" }, "agentName": { "type": "string" }, "userId": { "nullable": true, "description": "Who made the calls. Null for usage without a resolved user. Present when grouped by userId.", "type": "string" }, "userName": { "nullable": true, "type": "string" }, "authMethod": { "description": "How the request authenticated, e.g. virtual_key. Present when grouped by credentialId.", "type": "string" }, "credentialId": { "description": "Virtual key, passthrough key or OAuth client that made the requests. Null when the access method has no individual credential. Present when grouped by credentialId.", "nullable": true, "type": "string" }, "credentialName": { "nullable": true, "type": "string" }, "provider": { "description": "LLM provider, e.g. anthropic. Present when grouped by provider.", "type": "string" }, "model": { "description": "Billed model. A request that billed several models counts its tokens and spend under each one, and its request under the model it asked for. Present when grouped by model.", "type": "string" }, "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number", "description": "Newly processed input, cache writes and output." }, "billedCost": { "type": "number", "description": "Spend on metered API keys." }, "subscriptionCost": { "type": "number", "description": "Subscription usage valued at API rates; not a bill." } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "requests": { "type": "number" }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number", "description": "Newly processed input, cache writes and output." }, "billedCost": { "type": "number", "description": "Spend on metered API keys." }, "subscriptionCost": { "type": "number", "description": "Subscription usage valued at API rates; not a bill." } }, "required": [ "requests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "required": [ "data", "pagination", "totals" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/app-usage": { "get": { "operationId": "getAppUsage", "tags": [ "Statistics" ], "description": "Get app usage grouped by any combination of `day`, `appId` and `userId` — one row per group: times the app was opened, tool calls it made, and the LLM requests, tokens and spend it generated. Group by `day` (UTC calendar days) for a daily series. Apps outside the caller's visibility are excluded, and callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`app:read`](/docs/reference/permissions#app:read): Open Apps\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "userId", "required": false, "description": "Only this person's usage." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "teamId", "required": false, "description": "Only usage by direct members of this team." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "day", "appId", "userId" ] } }, "in": "query", "name": "groupBy", "required": false, "description": "Comma-separated dimensions to group by: day, appId, userId. Defaults to appId." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "appId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "UTC calendar day (YYYY-MM-DD). Present when grouped by day." }, "appId": { "type": "string" }, "appName": { "nullable": true, "type": "string" }, "userId": { "nullable": true, "description": "Who made the calls. Null for usage without a resolved user. Present when grouped by userId.", "type": "string" }, "userName": { "nullable": true, "type": "string" }, "runs": { "type": "number", "description": "Times the app was opened." }, "toolCalls": { "type": "number", "description": "Tool calls the app made." }, "llmRequests": { "type": "number", "description": "LLM requests the app made." }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "totalTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "runs", "toolCalls", "llmRequests", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "runs": { "type": "number", "description": "Times the app was opened." }, "toolCalls": { "type": "number", "description": "Tool calls the app made." }, "llmRequests": { "type": "number", "description": "LLM requests the app made." }, "inputTokens": { "type": "number" }, "outputTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "runs", "toolCalls", "llmRequests", "inputTokens", "outputTokens", "billedCost", "subscriptionCost" ], "additionalProperties": false } }, "required": [ "data", "pagination", "totals" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "app:read", "llmCost:read" ] } } }, "/api/statistics/skill-usage": { "get": { "operationId": "getSkillUsage", "tags": [ "Statistics" ], "description": "Get skill usage grouped by any combination of `day`, `skillId` and `userId` — one row per group: activations, the context tokens they added, and how many distinct people activated a skill. Group by `day` (UTC calendar days) for a daily series. Covers the organization's own skills. Skills outside the caller's scope are excluded, and callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics\n[`skill:read`](/docs/reference/permissions#skill:read): Open Skills", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "userId", "required": false, "description": "Only this person's usage." }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "teamId", "required": false, "description": "Only usage by direct members of this team." }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "day", "skillId", "userId" ] } }, "in": "query", "name": "groupBy", "required": false, "description": "Comma-separated dimensions to group by: day, skillId, userId. Defaults to skillId." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "skillId", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "UTC calendar day (YYYY-MM-DD). Present when grouped by day." }, "skillId": { "type": "string" }, "skillName": { "type": "string" }, "userId": { "nullable": true, "description": "Who made the calls. Null for usage without a resolved user. Present when grouped by userId.", "type": "string" }, "userName": { "nullable": true, "type": "string" }, "activations": { "type": "number" }, "contextTokens": { "type": "number", "description": "Tokens the activations added to the model's context." }, "users": { "type": "number", "description": "Distinct people who activated a skill." } }, "required": [ "activations", "contextTokens", "users" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false }, "totals": { "type": "object", "properties": { "activations": { "type": "number" }, "contextTokens": { "type": "number", "description": "Tokens the activations added to the model's context." }, "users": { "type": "number", "description": "Distinct people who activated a skill." } }, "required": [ "activations", "contextTokens", "users" ], "additionalProperties": false } }, "required": [ "data", "pagination", "totals" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmCost:read", "skill:read" ] } } }, "/api/statistics/model-usage": { "get": { "operationId": "getModelUsage", "tags": [ "Statistics" ], "description": "Break down one model's recorded usage by person, credential, agent or client. Totals and timelines use the same model and timeframe. Unattributed usage remains visible. The personal endpoint always reports only the caller's activity. Callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage, since a key or agent can be someone's personal one.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmCost:read`](/docs/reference/permissions#llmCost:read): View organization-wide LLM usage cost statistics and analytics", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "query", "name": "model", "required": true }, { "schema": { "default": "person", "type": "string", "enum": [ "person", "key", "agent", "client" ] }, "in": "query", "name": "groupBy", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "requests": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "requests": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "requests", "totalTokens", "cacheReadTokens", "cacheWriteTokens", "billedCost", "subscriptionCost" ], "additionalProperties": false } } }, "required": [ "id", "name", "requests", "totalTokens", "cacheReadTokens", "cacheWriteTokens", "billedCost", "subscriptionCost", "timeSeries" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmCost:read" ] } } }, "/api/statistics/me/model-usage": { "get": { "operationId": "getMyModelUsage", "tags": [ "Statistics" ], "description": "Break down one model's recorded usage by person, credential, agent or client. Totals and timelines use the same model and timeframe. Unattributed usage remains visible. The personal endpoint always reports only the caller's activity. Callers without [`member:read`](/docs/reference/permissions#member:read) see only their own usage, since a key or agent can be someone's personal one.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": "24h", "anyOf": [ { "type": "string", "enum": [ "5m", "15m", "30m", "1h", "24h", "7d", "30d", "90d", "12m", "all" ] }, { "type": "string", "pattern": "^custom:[\\s\\S]{0,}_[\\s\\S]{0,}$", "description": "Custom timeframe must be in format 'custom:startTime_endTime'" } ] }, "in": "query", "name": "timeframe", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "in": "query", "name": "model", "required": true }, { "schema": { "default": "client", "type": "string", "enum": [ "person", "key", "agent", "client" ] }, "in": "query", "name": "groupBy", "required": false }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "requests": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" }, "timeSeries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "requests": { "type": "number" }, "totalTokens": { "type": "number" }, "cacheReadTokens": { "type": "number" }, "cacheWriteTokens": { "type": "number" }, "billedCost": { "type": "number" }, "subscriptionCost": { "type": "number" } }, "required": [ "timestamp", "requests", "totalTokens", "cacheReadTokens", "cacheWriteTokens", "billedCost", "subscriptionCost" ], "additionalProperties": false } } }, "required": [ "id", "name", "requests", "totalTokens", "cacheReadTokens", "cacheWriteTokens", "billedCost", "subscriptionCost", "timeSeries" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/teams": { "get": { "operationId": "getTeams", "tags": [ "Teams" ], "description": "Get all teams in the organization\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeRelations", "required": false, "description": "Include team members, labels and descendant teams (default true). Set to false to get only the team fields and memberCount." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeMembers", "required": false, "description": "Include the members array of each team (default true). Set to false to get labels and descendant teams without members. Use memberCount for the number of members." }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "mine", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "organizationId": { "type": "string" }, "parentId": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "myRole": { "type": "string", "enum": [ "admin", "member" ] }, "descendantTeams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "memberCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "description", "roles", "organizationId", "parentId", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt", "memberCount" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } }, "post": { "operationId": "createTeam", "tags": [ "Teams" ], "description": "Create a new team\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:create`](/docs/reference/permissions#team:create): Create new teams", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string" }, "roles": { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_]+$" } }, "parentId": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "organizationId": { "type": "string" }, "parentId": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "myRole": { "type": "string", "enum": [ "admin", "member" ] }, "descendantTeams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "roles", "organizationId", "parentId", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:create" ] } } }, "/api/teams/{id}": { "get": { "operationId": "getTeam", "tags": [ "Teams" ], "description": "Get a team by ID, with the caller's role in it as myRole when they are a member\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "includeMembers", "required": false, "description": "Include the team's members array (default true). Set to false for a large team when only its details are needed; page through members with GET /api/teams/{id}/members/page." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "organizationId": { "type": "string" }, "parentId": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "myRole": { "type": "string", "enum": [ "admin", "member" ] }, "descendantTeams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "roles", "organizationId", "parentId", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } }, "put": { "operationId": "updateTeam", "tags": [ "Teams" ], "description": "Update a team\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": { "type": "string" }, "roles": { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_]+$" } }, "parentId": { "nullable": true, "type": "string" }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "organizationId": { "type": "string" }, "parentId": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "string" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "myRole": { "type": "string", "enum": [ "admin", "member" ] }, "descendantTeams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "description", "roles", "organizationId", "parentId", "createdBy", "createdByServiceAccountId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteTeam", "tags": [ "Teams" ], "description": "Delete a team\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:delete`](/docs/reference/permissions#team:delete): Delete teams", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:delete" ] } } }, "/api/teams/bulk": { "delete": { "operationId": "bulkDeleteTeams", "tags": [ "Teams" ], "description": "Delete several teams in one request. Ids outside the caller's organization are reported in `failed` as not found and leave the rest of the batch applied. Resources scoped to a deleted team lose that assignment, exactly as they do on the single-team delete.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:delete`](/docs/reference/permissions#team:delete): Delete teams", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:delete" ] } } }, "/api/teams/{id}/members": { "get": { "operationId": "getTeamMembers", "tags": [ "Teams" ], "description": "Get all members of a team\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "image": { "nullable": true, "type": "string" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt", "name", "email", "image" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } }, "post": { "operationId": "addTeamMember", "tags": [ "Teams" ], "description": "Add a member to a team\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "role": { "default": "member", "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "userId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/teams/{id}/members/page": { "get": { "operationId": "getTeamMembersPage", "tags": [ "Teams" ], "description": "Get one page of a team's members, ordered by name, with optional search\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "search", "required": false, "description": "Search by user name or email. Every whitespace-separated word must appear in the name or the email." }, { "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "userIds", "required": false, "description": "Return only these users (comma-separated, at most 100), to check which of them are members. With search, a user must match both." }, { "schema": { "type": "string", "enum": [ "admin", "member" ] }, "in": "query", "name": "role", "required": false, "description": "Return only members with this team role." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "nullable": true, "type": "string" }, "email": { "type": "string" }, "image": { "nullable": true, "type": "string" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt", "name", "email", "image" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/teams/{id}/members/{userId}": { "put": { "operationId": "updateTeamMember", "tags": [ "Teams" ], "description": "Update a team member role\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "role" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string" }, "syncedFromSso": { "type": "boolean" }, "roleSyncedFromSso": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "userId", "role", "syncedFromSso", "roleSyncedFromSso", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } }, "delete": { "operationId": "removeTeamMember", "tags": [ "Teams" ], "description": "Remove a member from a team\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/teams/labels/keys": { "get": { "operationId": "getTeamLabelKeys", "tags": [ "Teams" ], "description": "Get all label keys used by teams\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/teams/labels/values": { "get": { "operationId": "getTeamLabelValues", "tags": [ "Teams" ], "description": "Get all label values used by teams\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/teams/{id}/external-groups": { "get": { "operationId": "getTeamExternalGroups", "tags": [ "Teams" ], "description": "Get all external groups mapped to a team for SSO team sync\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "groupIdentifier": { "type": "string" }, "identityProviderId": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "groupIdentifier", "identityProviderId", "role", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } }, "post": { "operationId": "addTeamExternalGroup", "tags": [ "Teams" ], "description": "Link an identity provider group to a team for Team Sync\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupIdentifier": { "type": "string", "minLength": 1 }, "identityProviderId": { "description": "Match the group only for sign-ins through this identity provider. Omit to match it from any provider.", "nullable": true, "type": "string", "minLength": 1 }, "role": { "default": "member", "description": "The team role members of this group receive.", "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "groupIdentifier" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "groupIdentifier": { "type": "string" }, "identityProviderId": { "nullable": true, "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "groupIdentifier", "identityProviderId", "role", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/teams/{id}/external-groups/{groupId}": { "delete": { "operationId": "removeTeamExternalGroup", "tags": [ "Teams" ], "description": "Unlink an identity provider group from a team's Team Sync\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "groupId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/tools": { "get": { "operationId": "getTools", "tags": [ "Tools" ], "description": "Get a paginated list of tools\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "catalogId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToAgentId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "delegateToA2aConnectionId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "rawName": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "description": { "nullable": true, "type": "string" }, "meta": { "nullable": true, "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ] }, "clonedPendingDiscovery": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "nullable": true, "type": "string", "format": "date-time" }, "agent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "catalog": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "catalogId", "delegateToAgentId", "delegateToA2aConnectionId", "name", "rawName", "description", "meta", "clonedPendingDiscovery", "createdAt", "updatedAt", "deletedAt", "agent", "catalog" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/tools/with-assignments": { "get": { "operationId": "getToolsWithAssignments", "tags": [ "Tools" ], "description": "Get all tools with their profile assignments (one entry per tool)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpRegistry:read`](/docs/reference/permissions#mcpRegistry:read): Open the MCP registry and use its built-in servers", "parameters": [ { "schema": { "type": "string", "enum": [ "name", "origin", "createdAt", "assignmentCount" ] }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sortDirection", "required": false }, { "schema": { "type": "string", "maxLength": 512 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "origin", "required": false, "description": "Can be 'llm-proxy', 'agent', 'app', or a catalogId" }, { "schema": { "type": "string" }, "in": "query", "name": "observedByUserId", "required": false, "description": "Only tools observed in this user's LLM proxy traffic" }, { "schema": { "type": "string", "enum": [ "claude", "claude-code", "claude-desktop", "codex", "chatgpt", "copilot-cli", "cursor", "opencode", "kilo", "pi", "kimi-code" ] }, "in": "query", "name": "observedByClient", "required": false, "description": "Only tools observed from this client app family (e.g. claude, codex)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "excludeArchestraTools", "required": false, "description": "Hide built-in Archestra tools" }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeKnowledgeSourcesTool", "required": false, "description": "Include the built-in query_knowledge_sources tool in global listings (default: hidden)" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "anyOf": [ { "description": "\n https://github.com/openai/openai-node/blob/master/src/resources/shared.ts#L217\n\n The parameters the functions accepts, described as a JSON Schema object. See the\n [guide](https://platform.openai.com/docs/guides/function-calling) for examples,\n and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for\n documentation about the format.\n\n Omitting parameters defines a function with an empty parameter list.\n ", "type": "object", "additionalProperties": {} } ] }, "annotations": { "nullable": true, "type": "object", "additionalProperties": {} }, "catalogId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "assignmentCount": { "type": "number" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "agentToolId": { "type": "string" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "mcpServerId": { "nullable": true, "type": "string" }, "credentialOwnerEmail": { "nullable": true, "type": "string" }, "executionOwnerEmail": { "nullable": true, "type": "string" }, "credentialResolutionMode": { "type": "string", "enum": [ "static", "dynamic", "enterprise_managed" ] } }, "required": [ "agentToolId", "agent", "mcpServerId", "credentialOwnerEmail", "executionOwnerEmail", "credentialResolutionMode" ], "additionalProperties": false } }, "delegateToAgent": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "ownerEmail": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "scope", "ownerEmail" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "annotations", "catalogId", "createdAt", "updatedAt", "assignmentCount", "assignments", "delegateToAgent" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpRegistry:read" ] } } }, "/api/user/permission-sources": { "get": { "operationId": "getUserPermissionSources", "tags": [ "User" ], "description": "Get the direct roles and teams granting the current user's permissions\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "team": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "permissions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } } }, "required": [ "role", "team", "permissions" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/user/permissions": { "get": { "operationId": "getUserPermissions", "tags": [ "User" ], "description": "Get current user's permissions\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "create", "read", "update", "delete", "cancel", "query", "impersonate", "full-view", "admin" ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/user/impersonable": { "get": { "operationId": "getImpersonableUsers", "tags": [ "User" ], "description": "Search users in the caller's organization that admins can impersonate (role debugger) in bounded pages. The caller is excluded.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`member:impersonate`](/docs/reference/permissions#member:impersonate): Temporarily sign in as another member to see the app with their access (role debugging)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false, "description": "Matches name or email" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "nextCursor": { "nullable": true, "type": "string" }, "hasNext": { "type": "boolean" } }, "required": [ "limit", "nextCursor", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "member:impersonate" ] } } }, "/api/user-tokens/me": { "get": { "operationId": "getUserToken", "tags": [ "User Tokens" ], "description": "Get current user's personal token\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "id", "name", "tokenStart", "createdAt", "lastUsedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/user-tokens/me/value": { "get": { "operationId": "getUserTokenValue", "tags": [ "User Tokens" ], "description": "Get the full personal token value\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } }, "required": [ "value" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/user-tokens/me/rotate": { "post": { "operationId": "rotateUserToken", "tags": [ "User Tokens" ], "description": "Rotate personal token (generate new value)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "tokenStart": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "value": { "type": "string" } }, "required": [ "id", "name", "tokenStart", "createdAt", "lastUsedAt", "value" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-virtual-keys/labels/keys": { "get": { "operationId": "virtualApiKeyLabelKeys", "tags": [ "Virtual API Keys" ], "description": "Get all label keys used by virtual API keys\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmVirtualKey:read`](/docs/reference/permissions#llmVirtualKey:read): Open LLM virtual keys", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmVirtualKey:read" ] } } }, "/api/llm-virtual-keys/labels/values": { "get": { "operationId": "virtualApiKeyLabelValues", "tags": [ "Virtual API Keys" ], "description": "Get all label values used by virtual API keys\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmVirtualKey:read`](/docs/reference/permissions#llmVirtualKey:read): Open LLM virtual keys", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "key", "required": false, "description": "Filter values by label key" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmVirtualKey:read" ] } } }, "/api/llm-virtual-keys": { "get": { "operationId": "getAllVirtualApiKeys", "tags": [ "Virtual API Keys" ], "description": "Get virtual API keys visible to the current user, with provider key mappings\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "providerApiKeyId", "required": false }, { "schema": { "type": "string", "enum": [ "standard", "passthrough" ] }, "in": "query", "name": "keyType", "required": false }, { "schema": { "type": "string", "enum": [ "personal", "team", "org" ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "labels", "required": false, "description": "Filter by labels. Format: key1:val1|val2;key2:val3. AND across keys, OR within values." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "mine", "shared", "org", "others" ] } }, "in": "query", "name": "access", "required": false, "description": "Keep only objects the caller reaches in one of these ways (comma-separated): mine (authored by the caller), shared (shared with the caller or one of their teams), org (shared with the organization), others (visible only through organization-wide authority). Omit for every readable object." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "sharedWith", "required": false, "description": "Keep only objects whose own permissions grant read to one of these subjects (comma-separated): org (the whole organization), role:, team:, user:, serviceAccount:, oauthClient:. Grants inherited from organization-wide permissions do not count. Omit for no filtering." }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "in": "query", "name": "owner", "required": false, "description": "Keep only objects authored by one of these user IDs (comma-separated). Narrows the rows the caller can already read. Omit for no filtering." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "keyType": { "type": "string", "enum": [ "standard", "passthrough" ] }, "includeFutureProviders": { "type": "boolean" }, "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenStart": { "type": "string", "maxLength": 16 }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "billingTeamId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "keyType", "includeFutureProviders", "secretId", "tokenStart", "scope", "authorId", "expiresAt", "createdByServiceAccountId", "billingTeamId", "createdAt", "lastUsedAt", "teams", "authorName", "createdBy", "providerApiKeys", "labels", "billingTeam", "spendCap" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "currentPage", "limit", "total", "totalPages", "hasNext", "hasPrev" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createVirtualApiKey", "tags": [ "Virtual API Keys" ], "description": "Create a new virtual API key. Team admins creating a key for another member receive metadata only; the owner can retrieve its value.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`llmVirtualKey:create`](/docs/reference/permissions#llmVirtualKey:create): Create LLM virtual keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "keyType": { "default": "standard", "type": "string", "enum": [ "standard", "passthrough" ] }, "expiresAt": { "nullable": true }, "includeFutureProviders": { "type": "boolean" }, "providerApiKeys": { "default": [], "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ] } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "billingTeamId": { "nullable": true, "type": "string" }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] } }, "required": [ "limitValue", "cleanupInterval" ] }, "modelPoolIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "ownerId": { "type": "string" }, "initialGrants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "keyType": { "type": "string", "enum": [ "standard", "passthrough" ] }, "includeFutureProviders": { "type": "boolean" }, "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenStart": { "type": "string", "maxLength": 16 }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "billingTeamId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "value": { "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "keyType", "includeFutureProviders", "secretId", "tokenStart", "scope", "authorId", "expiresAt", "createdByServiceAccountId", "billingTeamId", "createdAt", "lastUsedAt", "teams", "authorName", "createdBy", "providerApiKeys", "labels", "billingTeam", "spendCap" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "llmVirtualKey:create" ] } } }, "/api/llm-virtual-keys/{id}": { "get": { "operationId": "getVirtualApiKey", "tags": [ "Virtual API Keys" ], "description": "Get a virtual API key visible to the current user, with provider key mappings\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "keyType": { "type": "string", "enum": [ "standard", "passthrough" ] }, "includeFutureProviders": { "type": "boolean" }, "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenStart": { "type": "string", "maxLength": 16 }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "billingTeamId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "keyType", "includeFutureProviders", "secretId", "tokenStart", "scope", "authorId", "expiresAt", "createdByServiceAccountId", "billingTeamId", "createdAt", "lastUsedAt", "teams", "authorName", "createdBy", "providerApiKeys", "labels", "billingTeam", "spendCap" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "patch": { "operationId": "updateVirtualApiKey", "tags": [ "Virtual API Keys" ], "description": "Update a virtual API key\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "keyType": { "default": "standard", "type": "string", "enum": [ "standard", "passthrough" ] }, "expiresAt": { "nullable": true }, "includeFutureProviders": { "type": "boolean" }, "providerApiKeys": { "default": [], "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "provider", "providerApiKeyId" ] } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ] } }, "billingTeamId": { "nullable": true, "type": "string" }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] } }, "required": [ "limitValue", "cleanupInterval" ] }, "modelPoolIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "autoRouterIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organizationId": { "type": "string" }, "name": { "type": "string", "maxLength": 256 }, "keyType": { "type": "string", "enum": [ "standard", "passthrough" ] }, "includeFutureProviders": { "type": "boolean" }, "secretId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenStart": { "type": "string", "maxLength": 16 }, "scope": { "type": "string", "enum": [ "personal", "team", "org" ] }, "authorId": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdByServiceAccountId": { "nullable": true, "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "billingTeamId": { "nullable": true, "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "authorName": { "nullable": true, "type": "string" }, "createdBy": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "service_account" ] }, "name": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "id", "name", "email" ], "additionalProperties": false }, "providerApiKeys": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "gemini", "anthropic", "bedrock", "cohere", "cerebras", "mistral", "perplexity", "groq", "xai", "openrouter", "vllm", "ollama", "ollama-native", "zhipuai", "deepseek", "minimax", "kimi", "kimi-code", "azure", "github-copilot", "microsoft-365-copilot", "archestra", "voyage", "jev" ] }, "providerApiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerApiKeyName": { "type": "string" } }, "required": [ "provider", "providerApiKeyId", "providerApiKeyName" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "valueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "key", "value" ], "additionalProperties": false } }, "billingTeam": { "nullable": true, "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "spendCap": { "nullable": true, "type": "object", "properties": { "limitValue": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "cleanupInterval": { "type": "string", "enum": [ "1h", "12h", "24h", "1w", "1m", "calendar_day", "calendar_week_sunday", "calendar_week_monday", "calendar_month" ] }, "limitId": { "type": "string" }, "currentUsage": { "type": "number" }, "estimatedUsage": { "type": "boolean" } }, "required": [ "limitValue", "cleanupInterval", "limitId", "currentUsage", "estimatedUsage" ], "additionalProperties": false } }, "required": [ "id", "organizationId", "name", "keyType", "includeFutureProviders", "secretId", "tokenStart", "scope", "authorId", "expiresAt", "createdByServiceAccountId", "billingTeamId", "createdAt", "lastUsedAt", "teams", "authorName", "createdBy", "providerApiKeys", "labels", "billingTeam", "spendCap" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteVirtualApiKey", "tags": [ "Virtual API Keys" ], "description": "Delete a virtual API key\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-virtual-keys/{id}/value": { "get": { "operationId": "getVirtualApiKeyValue", "tags": [ "Virtual API Keys" ], "description": "Get the raw value of a virtual API key. Only the key's author can reveal it; a key created by a service account with no owner is revealed to that service account.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } }, "required": [ "value" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/llm-virtual-keys/bulk": { "delete": { "operationId": "bulkDeleteVirtualApiKeys", "tags": [ "Virtual API Keys" ], "description": "Delete several virtual API keys in one request. Each id is authorized exactly as the single-key delete authorizes its own, so a key the caller cannot see or manage is reported in `failed` while the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/vllm/embeddings": { "post": { "operationId": "vllmEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with vLLM (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/vllm/{agentId}/embeddings": { "post": { "operationId": "vllmEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with vLLM for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/vllm/chat/completions": { "post": { "operationId": "vllmChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with vLLM (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VllmChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for vLLM (often not required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VllmChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/vllm/{agentId}/chat/completions": { "post": { "operationId": "vllmChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with vLLM for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VllmChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false, "description": "Bearer token for vLLM (often not required)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VllmChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/native/{kind}": { "get": { "operationId": "xaiNativeMetadataWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Read authenticated native Grok subscription metadata. Does not admit an inference session.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "enum": [ "models", "settings", "login-config" ] }, "in": "path", "name": "kind", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/native/privacy/coding-data-retention": { "put": { "operationId": "xaiNativePrivacyWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Update the caller's native Grok coding-data-sharing preference.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codingDataRetentionOptOut": { "type": "boolean" } }, "required": [ "codingDataRetentionOptOut" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "codingDataRetentionOptOut": { "type": "boolean" } }, "required": [ "codingDataRetentionOptOut" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/{agentId}/native/{kind}": { "get": { "operationId": "xaiNativeMetadataWithAgent", "tags": [ "LLM Proxy" ], "description": "Read authenticated native Grok subscription metadata. Does not admit an inference session.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string", "enum": [ "models", "settings", "login-config" ] }, "in": "path", "name": "kind", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/{agentId}/native/privacy/coding-data-retention": { "put": { "operationId": "xaiNativePrivacyWithAgent", "tags": [ "LLM Proxy" ], "description": "Update the caller's native Grok coding-data-sharing preference.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codingDataRetentionOptOut": { "type": "boolean" } }, "required": [ "codingDataRetentionOptOut" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "codingDataRetentionOptOut": { "type": "boolean" } }, "required": [ "codingDataRetentionOptOut" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/models": { "get": { "operationId": "xaiListModelsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "List available xAI models (default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/{agentId}/models": { "get": { "operationId": "xaiListModelsWithAgent", "tags": [ "LLM Proxy" ], "description": "List available xAI models (specific agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "model" ] }, "created": { "type": "number" }, "owned_by": { "type": "string" } }, "required": [ "id", "object", "created", "owned_by" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/chat/completions": { "post": { "operationId": "xaiChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with xAI (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/{agentId}/chat/completions": { "post": { "operationId": "xaiChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with xAI for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XaiChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/responses": { "post": { "operationId": "xaiResponsesWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with xAI (uses default agent). Served over xAI's chat completions.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/xai/{agentId}/responses": { "post": { "operationId": "xaiResponsesWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a response with xAI for a specific agent. Served over xAI's chat completions.\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } ] }, "instructions": { "nullable": true, "type": "string" }, "max_output_tokens": { "nullable": true, "type": "number" }, "metadata": { "nullable": true, "type": "object", "additionalProperties": { "type": "string" } }, "previous_response_id": { "nullable": true, "type": "string" }, "stream": { "nullable": true, "type": "boolean" }, "temperature": { "nullable": true, "type": "number" }, "text": {}, "tool_choice": {}, "tools": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ] }, "name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "parameters": { "nullable": true, "type": "object", "additionalProperties": {} }, "strict": { "nullable": true, "type": "boolean" } }, "required": [ "type", "name" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } ] } }, "top_p": { "nullable": true, "type": "number" }, "user": { "type": "string" } }, "required": [ "model" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" } } }, "description": "https://developers.openai.com/api/reference/resources/responses/methods/create" }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" }, { "schema": { "type": "string", "enum": [ "native-session" ] }, "in": "header", "name": "x-archestra-grok-credential-mode", "required": false }, { "schema": { "type": "string" }, "in": "header", "name": "x-xai-token-auth", "required": false } ], "responses": { "200": { "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "response" ] }, "created_at": { "type": "number" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "message" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "status": { "type": "string" }, "content": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_text%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "refusal" ] }, "refusal": { "type": "string" } }, "required": [ "type", "refusal" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_refusal%20%3E%20(schema)" } ] } } }, "required": [ "id", "type", "role", "status", "content" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_output_message%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function_call" ] }, "id": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "arguments": { "type": "string" }, "status": { "type": "string" } }, "required": [ "type", "call_id", "name", "arguments" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {} } ] } }, "status": { "type": "string" }, "usage": { "nullable": true, "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response_usage%20%3E%20(schema)" } }, "required": [ "id", "object", "created_at", "model", "output", "status" ], "additionalProperties": {}, "description": "https://developers.openai.com/api/reference/resources/responses#(resource)%20responses%20%3E%20(model)%20response%20%3E%20(schema)" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/xai-subscription-auth/device/start": { "post": { "operationId": "xaiSubscriptionDeviceAuthStart", "tags": [ "xAI Subscription Auth" ], "description": "Start the xAI OAuth device flow used to connect a SuperGrok subscription as a provider credential\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string" }, "userCode": { "type": "string" }, "verificationUri": { "type": "string" }, "interval": { "type": "number" }, "expiresIn": { "type": "number" } }, "required": [ "deviceCode", "userCode", "verificationUri", "interval", "expiresIn" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/xai-subscription-auth/device/poll": { "post": { "operationId": "xaiSubscriptionDeviceAuthPoll", "tags": [ "xAI Subscription Auth" ], "description": "Poll the xAI OAuth device flow once; returns the encoded provider credential when the user has authorized\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceCode": { "type": "string", "minLength": 1 } }, "required": [ "deviceCode" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "slow_down" ] } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete" ] }, "credential": { "type": "string" } }, "required": [ "status", "credential" ], "additionalProperties": false } ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/v1/zhipuai/embeddings": { "post": { "operationId": "zhipuaiEmbeddingsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Zhipu AI (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/zhipuai/{agentId}/embeddings": { "post": { "operationId": "zhipuaiEmbeddingsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create embeddings with Zhipu AI for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "dimensions": { "type": "number" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ] } }, "required": [ "model", "input" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for OpenAI" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "number" } }, "required": [ "object", "embedding" ], "additionalProperties": false } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "required": [ "prompt_tokens", "total_tokens" ], "additionalProperties": false } }, "required": [ "object", "data", "model", "usage" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/zhipuai/chat/completions": { "post": { "operationId": "zhipuaiChatCompletionsWithDefaultAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Zhipu AI (uses default agent)\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZhipuaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for Zhipu AI" }, { "schema": { "type": "string" }, "in": "header", "name": "accept-language", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZhipuaiChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/zhipuai/{agentId}/chat/completions": { "post": { "operationId": "zhipuaiChatCompletionsWithAgent", "tags": [ "LLM Proxy" ], "description": "Create a chat completion with Zhipu AI for a specific agent\n\nAuthentication:\n\nThis route accepts either an LLM provider API key or a Virtual API Key. See [LLM Proxy Authentication](/docs/llm-proxy/authentication).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZhipuaiChatCompletionRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "agentId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "user-agent", "required": false, "description": "The user agent of the client" }, { "schema": { "type": "string" }, "in": "header", "name": "authorization", "required": true, "description": "Bearer token for Zhipu AI" }, { "schema": { "type": "string" }, "in": "header", "name": "accept-language", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZhipuaiChatCompletionResponse" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/roles/bulk": { "delete": { "operationId": "bulkDeleteRoles", "tags": [ "Roles" ], "description": "Delete several custom roles in one request. A role that cannot be deleted — a predefined one, or one still held by a member — is reported in `failed` with that reason, and the rest of the batch still applies.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`ac:delete`](/docs/reference/permissions#ac:delete): Delete custom roles", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string" }, "description": "Ids to act on. Duplicates are collapsed." } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "affected": { "type": "number" }, "succeeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "nullable": true, "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "name", "error" ], "additionalProperties": false } } }, "required": [ "succeeded", "failed" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "ac:delete" ] } } }, "/api/identity-providers/public": { "get": { "operationId": "getPublicIdentityProviders", "tags": [ "Identity Providers" ], "description": "Get public identity provider list for login page (no secrets exposed)\n\nAuthentication:\n\nNot required.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "providerId": { "type": "string" } }, "required": [ "id", "providerId" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/identity-providers": { "get": { "operationId": "getIdentityProviders", "tags": [ "Identity Providers" ], "description": "Get all identity providers with configuration (admin only, secrets redacted)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`identityProvider:read`](/docs/reference/permissions#identityProvider:read): View identity provider configurations (SSO)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "issuer": { "type": "string" }, "oidcConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "skipDiscovery": { "type": "boolean" }, "pkce": { "type": "boolean" }, "enableRpInitiatedLogout": { "type": "boolean" }, "hd": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationEndpoint": { "type": "string" }, "discoveryEndpoint": { "type": "string" }, "userInfoEndpoint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "overrideUserInfo": { "type": "boolean" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "jwksEndpoint": { "type": "string" }, "enterpriseManagedCredentials": { "type": "object", "properties": { "exchangeStrategy": { "type": "string", "enum": [ "rfc8693", "okta_managed", "entra_obo" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "clientAssertionAudience": { "type": "string" }, "subjectTokenType": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" ] }, "entraAgentId": { "type": "object", "properties": { "blueprintClientId": { "type": "string" }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "certificateThumbprint": { "type": "string" }, "blueprintScope": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" } }, "required": [ "blueprintClientId" ], "additionalProperties": false }, "agentIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "client", "spiffe" ] }, "spiffeAudience": { "type": "string" }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" }, "actorTokenScope": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L3", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "pkce", "clientId", "discoveryEndpoint" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L22" }, "samlConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "entryPoint": { "type": "string" }, "cert": { "type": "string" }, "callbackUrl": { "type": "string" }, "audience": { "type": "string" }, "idpMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "entityURL": { "type": "string" }, "redirectURL": { "type": "string" }, "cert": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" }, "singleSignOnService": { "type": "array", "items": { "type": "object", "properties": { "Binding": { "type": "string" }, "Location": { "type": "string" } }, "required": [ "Binding", "Location" ], "additionalProperties": false } } }, "additionalProperties": false }, "spMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "binding": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" } }, "additionalProperties": false }, "wantAssertionsSigned": { "type": "boolean" }, "signatureAlgorithm": { "type": "string" }, "digestAlgorithm": { "type": "string" }, "identifierFormat": { "type": "string" }, "privateKey": { "type": "string" }, "decryptionPvk": { "type": "string" }, "additionalParams": { "type": "object", "additionalProperties": {} }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L12C30-L20C2", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "entryPoint", "cert", "callbackUrl", "spMetadata" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L40" }, "roleMapping": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string", "minLength": 1 }, "role": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } }, "required": [ "expression", "role" ], "additionalProperties": false } }, "defaultRole": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" }, "strictMode": { "type": "boolean" }, "skipRoleSync": { "type": "boolean" } }, "additionalProperties": false }, "teamSyncConfig": { "type": "object", "properties": { "groupsExpression": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "userId": { "nullable": true, "type": "string" }, "providerId": { "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "domain": { "type": "string" }, "domainVerified": { "nullable": true, "type": "boolean" }, "ssoLoginEnabled": { "type": "boolean" }, "configuredSecretPaths": { "type": "array", "items": { "type": "string", "enum": [ "oidcConfig.clientSecret", "oidcConfig.enterpriseManagedCredentials.clientSecret", "oidcConfig.enterpriseManagedCredentials.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.entraAgentId.clientSecret", "oidcConfig.enterpriseManagedCredentials.entraAgentId.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.agentIdentity.privateKeyPem", "samlConfig.privateKey", "samlConfig.decryptionPvk", "samlConfig.spMetadata.privateKey", "samlConfig.spMetadata.privateKeyPass", "samlConfig.spMetadata.encPrivateKey", "samlConfig.spMetadata.encPrivateKeyPass", "samlConfig.idpMetadata.privateKey", "samlConfig.idpMetadata.privateKeyPass", "samlConfig.idpMetadata.encPrivateKey", "samlConfig.idpMetadata.encPrivateKeyPass" ] } } }, "required": [ "id", "issuer", "userId", "providerId", "organizationId", "domain", "domainVerified", "ssoLoginEnabled", "configuredSecretPaths" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "identityProvider:read" ] } }, "post": { "operationId": "createIdentityProvider", "tags": [ "Identity Providers" ], "description": "Create a new identity provider (secrets redacted)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`identityProvider:create`](/docs/reference/permissions#identityProvider:create): Set up new identity providers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "oidcConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "skipDiscovery": { "type": "boolean" }, "pkce": { "type": "boolean" }, "enableRpInitiatedLogout": { "type": "boolean" }, "hd": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationEndpoint": { "type": "string" }, "discoveryEndpoint": { "type": "string" }, "userInfoEndpoint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "overrideUserInfo": { "type": "boolean" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "jwksEndpoint": { "type": "string" }, "enterpriseManagedCredentials": { "type": "object", "properties": { "exchangeStrategy": { "type": "string", "enum": [ "rfc8693", "okta_managed", "entra_obo" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "clientAssertionAudience": { "type": "string" }, "subjectTokenType": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" ] }, "entraAgentId": { "type": "object", "properties": { "blueprintClientId": { "type": "string" }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "certificateThumbprint": { "type": "string" }, "blueprintScope": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" } }, "required": [ "blueprintClientId" ] }, "agentIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "client", "spiffe" ] }, "spiffeAudience": { "type": "string" }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" }, "actorTokenScope": { "type": "string" } } } } }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L3", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "required": [ "issuer", "pkce", "clientId", "clientSecret", "discoveryEndpoint" ], "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L22" }, "samlConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "entryPoint": { "type": "string" }, "cert": { "type": "string" }, "callbackUrl": { "type": "string" }, "audience": { "type": "string" }, "idpMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "entityURL": { "type": "string" }, "redirectURL": { "type": "string" }, "cert": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" }, "singleSignOnService": { "type": "array", "items": { "type": "object", "properties": { "Binding": { "type": "string" }, "Location": { "type": "string" } }, "required": [ "Binding", "Location" ] } } } }, "spMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "binding": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" } } }, "wantAssertionsSigned": { "type": "boolean" }, "signatureAlgorithm": { "type": "string" }, "digestAlgorithm": { "type": "string" }, "identifierFormat": { "type": "string" }, "privateKey": { "type": "string" }, "decryptionPvk": { "type": "string" }, "additionalParams": { "type": "object", "additionalProperties": {} }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L12C30-L20C2", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "required": [ "issuer", "entryPoint", "cert", "callbackUrl", "spMetadata" ], "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L40" }, "roleMapping": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string", "minLength": 1 }, "role": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } }, "required": [ "expression", "role" ] } }, "defaultRole": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" }, "strictMode": { "type": "boolean" }, "skipRoleSync": { "type": "boolean" } } }, "teamSyncConfig": { "type": "object", "properties": { "groupsExpression": { "type": "string" }, "enabled": { "type": "boolean" } } }, "userId": { "nullable": true, "type": "string" }, "providerId": { "type": "string" }, "domain": { "type": "string" }, "domainVerified": { "nullable": true, "type": "boolean" }, "ssoLoginEnabled": { "type": "boolean" } }, "required": [ "issuer", "providerId", "domain" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "issuer": { "type": "string" }, "oidcConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "skipDiscovery": { "type": "boolean" }, "pkce": { "type": "boolean" }, "enableRpInitiatedLogout": { "type": "boolean" }, "hd": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationEndpoint": { "type": "string" }, "discoveryEndpoint": { "type": "string" }, "userInfoEndpoint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "overrideUserInfo": { "type": "boolean" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "jwksEndpoint": { "type": "string" }, "enterpriseManagedCredentials": { "type": "object", "properties": { "exchangeStrategy": { "type": "string", "enum": [ "rfc8693", "okta_managed", "entra_obo" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "clientAssertionAudience": { "type": "string" }, "subjectTokenType": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" ] }, "entraAgentId": { "type": "object", "properties": { "blueprintClientId": { "type": "string" }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "certificateThumbprint": { "type": "string" }, "blueprintScope": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" } }, "required": [ "blueprintClientId" ], "additionalProperties": false }, "agentIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "client", "spiffe" ] }, "spiffeAudience": { "type": "string" }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" }, "actorTokenScope": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L3", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "pkce", "clientId", "discoveryEndpoint" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L22" }, "samlConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "entryPoint": { "type": "string" }, "cert": { "type": "string" }, "callbackUrl": { "type": "string" }, "audience": { "type": "string" }, "idpMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "entityURL": { "type": "string" }, "redirectURL": { "type": "string" }, "cert": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" }, "singleSignOnService": { "type": "array", "items": { "type": "object", "properties": { "Binding": { "type": "string" }, "Location": { "type": "string" } }, "required": [ "Binding", "Location" ], "additionalProperties": false } } }, "additionalProperties": false }, "spMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "binding": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" } }, "additionalProperties": false }, "wantAssertionsSigned": { "type": "boolean" }, "signatureAlgorithm": { "type": "string" }, "digestAlgorithm": { "type": "string" }, "identifierFormat": { "type": "string" }, "privateKey": { "type": "string" }, "decryptionPvk": { "type": "string" }, "additionalParams": { "type": "object", "additionalProperties": {} }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L12C30-L20C2", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "entryPoint", "cert", "callbackUrl", "spMetadata" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L40" }, "roleMapping": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string", "minLength": 1 }, "role": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } }, "required": [ "expression", "role" ], "additionalProperties": false } }, "defaultRole": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" }, "strictMode": { "type": "boolean" }, "skipRoleSync": { "type": "boolean" } }, "additionalProperties": false }, "teamSyncConfig": { "type": "object", "properties": { "groupsExpression": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "userId": { "nullable": true, "type": "string" }, "providerId": { "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "domain": { "type": "string" }, "domainVerified": { "nullable": true, "type": "boolean" }, "ssoLoginEnabled": { "type": "boolean" }, "configuredSecretPaths": { "type": "array", "items": { "type": "string", "enum": [ "oidcConfig.clientSecret", "oidcConfig.enterpriseManagedCredentials.clientSecret", "oidcConfig.enterpriseManagedCredentials.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.entraAgentId.clientSecret", "oidcConfig.enterpriseManagedCredentials.entraAgentId.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.agentIdentity.privateKeyPem", "samlConfig.privateKey", "samlConfig.decryptionPvk", "samlConfig.spMetadata.privateKey", "samlConfig.spMetadata.privateKeyPass", "samlConfig.spMetadata.encPrivateKey", "samlConfig.spMetadata.encPrivateKeyPass", "samlConfig.idpMetadata.privateKey", "samlConfig.idpMetadata.privateKeyPass", "samlConfig.idpMetadata.encPrivateKey", "samlConfig.idpMetadata.encPrivateKeyPass" ] } } }, "required": [ "id", "issuer", "userId", "providerId", "organizationId", "domain", "domainVerified", "ssoLoginEnabled", "configuredSecretPaths" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "identityProvider:create" ] } } }, "/api/identity-providers/team-sync-options": { "get": { "operationId": "getIdentityProviderTeamSyncOptions", "tags": [ "Identity Providers" ], "description": "Get identity providers as minimal team-sync options (id, name, and groups extraction template) for linking external groups to teams\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "providerId": { "type": "string" }, "groupsExpression": { "nullable": true, "type": "string" } }, "required": [ "id", "providerId", "groupsExpression" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/identity-providers/idp-logout-url": { "get": { "operationId": "getIdentityProviderIdpLogoutUrl", "tags": [ "Identity Providers" ], "description": "Get the IdP logout URL for the current user's identity provider\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "nullable": true, "type": "string" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/identity-providers/{id}/link-status": { "get": { "operationId": "getIdentityProviderLinkStatus", "tags": [ "Identity Providers" ], "description": "Get whether the current user has a usable token for this identity provider\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`mcpServerInstallation:create`](/docs/reference/permissions#mcpServerInstallation:create): Install MCP servers from the registry", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "connected": { "type": "boolean" } }, "required": [ "providerId", "connected" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "mcpServerInstallation:create" ] } } }, "/api/identity-providers/{id}/latest-id-token-claims": { "get": { "operationId": "getIdentityProviderLatestIdTokenClaims", "tags": [ "Identity Providers" ], "description": "Get decoded claims from the current user's latest identity-provider tokens\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`team:read`](/docs/reference/permissions#team:read): View teams and their members", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string" }, "claims": { "nullable": true, "type": "object", "additionalProperties": {} }, "accessTokenClaims": { "nullable": true, "type": "object", "additionalProperties": {} }, "accessTokenExpiresAt": { "nullable": true, "type": "string", "format": "date-time" }, "updatedAt": { "nullable": true, "type": "string", "format": "date-time" } }, "required": [ "providerId", "claims", "accessTokenClaims", "accessTokenExpiresAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "team:read" ] } } }, "/api/identity-providers/{id}": { "get": { "operationId": "getIdentityProvider", "tags": [ "Identity Providers" ], "description": "Get identity provider by ID (secrets redacted)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`identityProvider:read`](/docs/reference/permissions#identityProvider:read): View identity provider configurations (SSO)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "issuer": { "type": "string" }, "oidcConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "skipDiscovery": { "type": "boolean" }, "pkce": { "type": "boolean" }, "enableRpInitiatedLogout": { "type": "boolean" }, "hd": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationEndpoint": { "type": "string" }, "discoveryEndpoint": { "type": "string" }, "userInfoEndpoint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "overrideUserInfo": { "type": "boolean" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "jwksEndpoint": { "type": "string" }, "enterpriseManagedCredentials": { "type": "object", "properties": { "exchangeStrategy": { "type": "string", "enum": [ "rfc8693", "okta_managed", "entra_obo" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "clientAssertionAudience": { "type": "string" }, "subjectTokenType": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" ] }, "entraAgentId": { "type": "object", "properties": { "blueprintClientId": { "type": "string" }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "certificateThumbprint": { "type": "string" }, "blueprintScope": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" } }, "required": [ "blueprintClientId" ], "additionalProperties": false }, "agentIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "client", "spiffe" ] }, "spiffeAudience": { "type": "string" }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" }, "actorTokenScope": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L3", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "pkce", "clientId", "discoveryEndpoint" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L22" }, "samlConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "entryPoint": { "type": "string" }, "cert": { "type": "string" }, "callbackUrl": { "type": "string" }, "audience": { "type": "string" }, "idpMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "entityURL": { "type": "string" }, "redirectURL": { "type": "string" }, "cert": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" }, "singleSignOnService": { "type": "array", "items": { "type": "object", "properties": { "Binding": { "type": "string" }, "Location": { "type": "string" } }, "required": [ "Binding", "Location" ], "additionalProperties": false } } }, "additionalProperties": false }, "spMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "binding": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" } }, "additionalProperties": false }, "wantAssertionsSigned": { "type": "boolean" }, "signatureAlgorithm": { "type": "string" }, "digestAlgorithm": { "type": "string" }, "identifierFormat": { "type": "string" }, "privateKey": { "type": "string" }, "decryptionPvk": { "type": "string" }, "additionalParams": { "type": "object", "additionalProperties": {} }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L12C30-L20C2", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "entryPoint", "cert", "callbackUrl", "spMetadata" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L40" }, "roleMapping": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string", "minLength": 1 }, "role": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } }, "required": [ "expression", "role" ], "additionalProperties": false } }, "defaultRole": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" }, "strictMode": { "type": "boolean" }, "skipRoleSync": { "type": "boolean" } }, "additionalProperties": false }, "teamSyncConfig": { "type": "object", "properties": { "groupsExpression": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "userId": { "nullable": true, "type": "string" }, "providerId": { "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "domain": { "type": "string" }, "domainVerified": { "nullable": true, "type": "boolean" }, "ssoLoginEnabled": { "type": "boolean" }, "configuredSecretPaths": { "type": "array", "items": { "type": "string", "enum": [ "oidcConfig.clientSecret", "oidcConfig.enterpriseManagedCredentials.clientSecret", "oidcConfig.enterpriseManagedCredentials.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.entraAgentId.clientSecret", "oidcConfig.enterpriseManagedCredentials.entraAgentId.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.agentIdentity.privateKeyPem", "samlConfig.privateKey", "samlConfig.decryptionPvk", "samlConfig.spMetadata.privateKey", "samlConfig.spMetadata.privateKeyPass", "samlConfig.spMetadata.encPrivateKey", "samlConfig.spMetadata.encPrivateKeyPass", "samlConfig.idpMetadata.privateKey", "samlConfig.idpMetadata.privateKeyPass", "samlConfig.idpMetadata.encPrivateKey", "samlConfig.idpMetadata.encPrivateKeyPass" ] } } }, "required": [ "id", "issuer", "userId", "providerId", "organizationId", "domain", "domainVerified", "ssoLoginEnabled", "configuredSecretPaths" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "identityProvider:read" ] } }, "put": { "operationId": "updateIdentityProvider", "tags": [ "Identity Providers" ], "description": "Update identity provider (secrets redacted)\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`identityProvider:update`](/docs/reference/permissions#identityProvider:update): Modify identity provider settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "oidcConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "skipDiscovery": { "type": "boolean" }, "pkce": { "type": "boolean" }, "enableRpInitiatedLogout": { "type": "boolean" }, "hd": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationEndpoint": { "type": "string" }, "discoveryEndpoint": { "type": "string" }, "userInfoEndpoint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "overrideUserInfo": { "type": "boolean" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "jwksEndpoint": { "type": "string" }, "enterpriseManagedCredentials": { "type": "object", "properties": { "exchangeStrategy": { "type": "string", "enum": [ "rfc8693", "okta_managed", "entra_obo" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "clientAssertionAudience": { "type": "string" }, "subjectTokenType": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" ] }, "entraAgentId": { "type": "object", "properties": { "blueprintClientId": { "type": "string" }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "certificateThumbprint": { "type": "string" }, "blueprintScope": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" } }, "required": [ "blueprintClientId" ] }, "agentIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "client", "spiffe" ] }, "spiffeAudience": { "type": "string" }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" }, "actorTokenScope": { "type": "string" } } } } }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L3", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "required": [ "issuer", "pkce", "clientId", "discoveryEndpoint" ], "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L22" }, "samlConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "entryPoint": { "type": "string" }, "cert": { "type": "string" }, "callbackUrl": { "type": "string" }, "audience": { "type": "string" }, "idpMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "entityURL": { "type": "string" }, "redirectURL": { "type": "string" }, "cert": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" }, "singleSignOnService": { "type": "array", "items": { "type": "object", "properties": { "Binding": { "type": "string" }, "Location": { "type": "string" } }, "required": [ "Binding", "Location" ] } } } }, "spMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "binding": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" } } }, "wantAssertionsSigned": { "type": "boolean" }, "signatureAlgorithm": { "type": "string" }, "digestAlgorithm": { "type": "string" }, "identifierFormat": { "type": "string" }, "privateKey": { "type": "string" }, "decryptionPvk": { "type": "string" }, "additionalParams": { "type": "object", "additionalProperties": {} }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L12C30-L20C2", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "required": [ "issuer", "entryPoint", "cert", "callbackUrl", "spMetadata" ], "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L40" }, "roleMapping": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string", "minLength": 1 }, "role": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } }, "required": [ "expression", "role" ] } }, "defaultRole": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" }, "strictMode": { "type": "boolean" }, "skipRoleSync": { "type": "boolean" } } }, "teamSyncConfig": { "type": "object", "properties": { "groupsExpression": { "type": "string" }, "enabled": { "type": "boolean" } } }, "providerId": { "type": "string" }, "domain": { "type": "string" }, "domainVerified": { "nullable": true, "type": "boolean" }, "ssoLoginEnabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "issuer": { "type": "string" }, "oidcConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "skipDiscovery": { "type": "boolean" }, "pkce": { "type": "boolean" }, "enableRpInitiatedLogout": { "type": "boolean" }, "hd": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "authorizationEndpoint": { "type": "string" }, "discoveryEndpoint": { "type": "string" }, "userInfoEndpoint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "overrideUserInfo": { "type": "boolean" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "jwksEndpoint": { "type": "string" }, "enterpriseManagedCredentials": { "type": "object", "properties": { "exchangeStrategy": { "type": "string", "enum": [ "rfc8693", "okta_managed", "entra_obo" ] }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "tokenEndpointAuthentication": { "type": "string", "enum": [ "client_secret_post", "client_secret_basic", "private_key_jwt" ] }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "clientAssertionAudience": { "type": "string" }, "subjectTokenType": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:jwt" ] }, "entraAgentId": { "type": "object", "properties": { "blueprintClientId": { "type": "string" }, "clientSecret": { "type": "string" }, "privateKeyPem": { "type": "string" }, "certificateThumbprint": { "type": "string" }, "blueprintScope": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" } }, "required": [ "blueprintClientId" ], "additionalProperties": false }, "agentIdentity": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "client", "spiffe" ] }, "spiffeAudience": { "type": "string" }, "privateKeyPem": { "type": "string" }, "privateKeyId": { "type": "string" }, "requireAgentIdentity": { "type": "boolean" }, "actorTokenScope": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L3", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "pkce", "clientId", "discoveryEndpoint" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L22" }, "samlConfig": { "type": "object", "properties": { "issuer": { "type": "string" }, "entryPoint": { "type": "string" }, "cert": { "type": "string" }, "callbackUrl": { "type": "string" }, "audience": { "type": "string" }, "idpMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "entityURL": { "type": "string" }, "redirectURL": { "type": "string" }, "cert": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" }, "singleSignOnService": { "type": "array", "items": { "type": "object", "properties": { "Binding": { "type": "string" }, "Location": { "type": "string" } }, "required": [ "Binding", "Location" ], "additionalProperties": false } } }, "additionalProperties": false }, "spMetadata": { "type": "object", "properties": { "metadata": { "type": "string" }, "entityID": { "type": "string" }, "binding": { "type": "string" }, "privateKey": { "type": "string" }, "privateKeyPass": { "type": "string" }, "isAssertionEncrypted": { "type": "boolean" }, "encPrivateKey": { "type": "string" }, "encPrivateKeyPass": { "type": "string" } }, "additionalProperties": false }, "wantAssertionsSigned": { "type": "boolean" }, "signatureAlgorithm": { "type": "string" }, "digestAlgorithm": { "type": "string" }, "identifierFormat": { "type": "string" }, "privateKey": { "type": "string" }, "decryptionPvk": { "type": "string" }, "additionalParams": { "type": "object", "additionalProperties": {} }, "mapping": { "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L12C30-L20C2", "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "string" }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "extraFields": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "issuer", "entryPoint", "cert", "callbackUrl", "spMetadata" ], "additionalProperties": false, "description": "https://github.com/better-auth/better-auth/blob/v1.4.0/packages/sso/src/types.ts#L40" }, "roleMapping": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "expression": { "type": "string", "minLength": 1 }, "role": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" } }, "required": [ "expression", "role" ], "additionalProperties": false } }, "defaultRole": { "type": "string", "pattern": "^[a-z0-9_:-]+(?:,[a-z0-9_:-]+)*$", "description": "One or more organization role identifiers, separated by commas" }, "strictMode": { "type": "boolean" }, "skipRoleSync": { "type": "boolean" } }, "additionalProperties": false }, "teamSyncConfig": { "type": "object", "properties": { "groupsExpression": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "userId": { "nullable": true, "type": "string" }, "providerId": { "type": "string" }, "organizationId": { "nullable": true, "type": "string" }, "domain": { "type": "string" }, "domainVerified": { "nullable": true, "type": "boolean" }, "ssoLoginEnabled": { "type": "boolean" }, "configuredSecretPaths": { "type": "array", "items": { "type": "string", "enum": [ "oidcConfig.clientSecret", "oidcConfig.enterpriseManagedCredentials.clientSecret", "oidcConfig.enterpriseManagedCredentials.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.entraAgentId.clientSecret", "oidcConfig.enterpriseManagedCredentials.entraAgentId.privateKeyPem", "oidcConfig.enterpriseManagedCredentials.agentIdentity.privateKeyPem", "samlConfig.privateKey", "samlConfig.decryptionPvk", "samlConfig.spMetadata.privateKey", "samlConfig.spMetadata.privateKeyPass", "samlConfig.spMetadata.encPrivateKey", "samlConfig.spMetadata.encPrivateKeyPass", "samlConfig.idpMetadata.privateKey", "samlConfig.idpMetadata.privateKeyPass", "samlConfig.idpMetadata.encPrivateKey", "samlConfig.idpMetadata.encPrivateKeyPass" ] } } }, "required": [ "id", "issuer", "userId", "providerId", "organizationId", "domain", "domainVerified", "ssoLoginEnabled", "configuredSecretPaths" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "identityProvider:update" ] } }, "delete": { "operationId": "deleteIdentityProvider", "tags": [ "Identity Providers" ], "description": "Delete identity provider\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\n[`identityProvider:delete`](/docs/reference/permissions#identityProvider:delete): Remove identity providers", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "static", "permissions": [ "identityProvider:delete" ] } } }, "/api/oauth-clients/{id}/federated-credentials": { "get": { "operationId": "getOauthClientFederatedCredentials", "tags": [ "OAuth Clients" ], "description": "List an OAuth client's federated credentials: the OIDC issuers, audiences, subjects and claims whose tokens authenticate as the client\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "oauthClientId": { "type": "string" }, "name": { "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "subject": { "type": "string" }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "oauthClientId", "name", "issuer", "audience", "subject", "claimConditions", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createOauthClientFederatedCredential", "tags": [ "OAuth Clients" ], "description": "Add a federated credential to an OAuth client that signs in as itself. A token from the issuer whose audience, subject and listed claims all match exactly can then be sent as the client_assertion of a client credentials grant at /api/auth/oauth2/token.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "issuer": { "type": "string", "maxLength": 2048 }, "audience": { "type": "string", "minLength": 1, "maxLength": 1024 }, "subject": { "type": "string", "minLength": 1, "maxLength": 1024 }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "required": [ "name", "issuer", "audience", "subject" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "oauthClientId": { "type": "string" }, "name": { "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "subject": { "type": "string" }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "oauthClientId", "name", "issuer", "audience", "subject", "claimConditions", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/oauth-clients/{id}/federated-credentials/{credentialId}": { "patch": { "operationId": "updateOauthClientFederatedCredential", "tags": [ "OAuth Clients" ], "description": "Update an OAuth client's federated credential. Changing its issuer, audience, subject or claims revokes the access tokens it already issued.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "issuer": { "type": "string", "maxLength": 2048 }, "audience": { "type": "string", "minLength": 1, "maxLength": 1024 }, "subject": { "type": "string", "minLength": 1, "maxLength": 1024 }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "credentialId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "oauthClientId": { "type": "string" }, "name": { "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "subject": { "type": "string" }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "oauthClientId", "name", "issuer", "audience", "subject", "claimConditions", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteOauthClientFederatedCredential", "tags": [ "OAuth Clients" ], "description": "Delete an OAuth client's federated credential. Access tokens it issued stop working at once.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "credentialId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/resource-permissions/{resource}/creation-subjects": { "get": { "operationId": "searchInitialPermissionSubjects", "tags": [ "Permissions" ], "parameters": [ { "schema": { "default": "", "type": "string", "maxLength": 200 }, "in": "query", "name": "query", "required": false }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "exclude", "required": false, "description": "Exclude already selected recipients, using comma-separated subject keys." }, { "schema": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "in": "path", "name": "resource", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "subject", "name" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/resource-permissions": { "get": { "operationId": "getScopedCapabilities", "tags": [ "Permissions" ], "description": "The signed-in actor's explicit scoped capabilities. Single-object grants that a `*` grant for the same resource and action covers are left out. Used for discovery; each operation still authorizes its target.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "resource": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "action": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "required": [ "organizationId", "resource", "scope", "action" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/resource-permissions/{resource}/{scope}/subjects": { "get": { "operationId": "searchResourcePermissionSubjects", "tags": [ "Permissions" ], "parameters": [ { "schema": { "default": "", "type": "string", "maxLength": 200 }, "in": "query", "name": "query", "required": false }, { "schema": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "exclude", "required": false, "description": "Exclude already selected recipients, using comma-separated subject keys." }, { "schema": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "in": "path", "name": "resource", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "in": "path", "name": "scope", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "subject", "name" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] }, "description": "Authentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)" } }, "/api/resource-permissions/{resource}/{scope}": { "get": { "operationId": "getResourcePermissions", "tags": [ "Permissions" ], "description": "Read direct grants and effective actions for an object or all objects of one resource type\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "in": "path", "name": "resource", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "in": "path", "name": "scope", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "name": { "type": "string" }, "ownerId": { "nullable": true, "type": "string" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "grants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "name": { "type": "string" } }, "required": [ "subject", "actions", "name" ], "additionalProperties": false } }, "inheritedGrants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "name": { "type": "string" }, "sourceScope": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] } }, "required": [ "subject", "actions", "name" ], "additionalProperties": false } }, "effectiveActions": { "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "canShareOrganizationWide": { "type": "boolean" }, "actorSubjects": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] } } }, "required": [ "resource", "scope", "name", "ownerId", "revision", "grants", "inheritedGrants", "effectiveActions", "canShareOrganizationWide", "actorSubjects" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "put": { "operationId": "updateResourcePermissions", "tags": [ "Permissions" ], "description": "Replace direct resource grants with optimistic concurrency and delegation checks\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "grants": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ] } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } } }, "required": [ "subject", "actions" ] } } }, "required": [ "revision", "grants" ] } } } }, "parameters": [ { "schema": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "in": "path", "name": "resource", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "in": "path", "name": "scope", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string", "enum": [ "agent", "mcpGateway", "mcpRegistry", "skill", "app", "llmModel", "project", "conversation", "agentRun", "plugin", "knowledgeBase", "knowledgeConnector", "knowledgeFile", "llmVirtualKey", "llmProviderApiKey", "externalAgent", "oauthClient", "environment", "agentRuntime", "serviceAccount", "credential" ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] }, "name": { "type": "string" }, "ownerId": { "nullable": true, "type": "string" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "grants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "name": { "type": "string" } }, "required": [ "subject", "actions", "name" ], "additionalProperties": false } }, "inheritedGrants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] }, "actions": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "name": { "type": "string" }, "sourceScope": { "anyOf": [ { "type": "string", "enum": [ "*" ] }, { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } ] } }, "required": [ "subject", "actions", "name" ], "additionalProperties": false } }, "effectiveActions": { "type": "array", "items": { "type": "string", "enum": [ "read", "use", "update", "delete", "manage-permissions", "configure-deployment-spec", "configure", "deploy-agent", "deploy-mcp-gateway", "deploy-mcp-registry", "deploy-skill", "deploy-app", "deploy-knowledge-source" ] } }, "canShareOrganizationWide": { "type": "boolean" }, "actorSubjects": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "serviceAccount" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauthClient" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "enum": [ "*" ] } }, "required": [ "type", "id" ], "additionalProperties": false } ] } } }, "required": [ "resource", "scope", "name", "ownerId", "revision", "grants", "inheritedGrants", "effectiveActions", "canShareOrganizationWide", "actorSubjects" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/rum/events": { "post": { "operationId": "ingestRumEvents", "tags": [ "RUM" ], "description": "Ingest a batch of product-usage (RUM) events from the web client. Events are forwarded as OTLP log records to the deployment-configured collector; when no RUM export endpoint is configured the batch is acknowledged and dropped.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "session.start", "archestra.session.heartbeat", "archestra.page_view", "browser.web_vital", "archestra.page_load", "archestra.long_task", "archestra.client_error", "archestra.api_request", "archestra.interaction", "archestra.user_authenticated", "archestra.onboarding_completed", "archestra.mcp_server_installed", "archestra.mcp_server_uninstalled", "archestra.mcp_server_installation_cancelled", "archestra.mcp_server_installation_failed", "archestra.knowledge_base_connector_installation_failed", "archestra.message_sent", "archestra.message_queued", "archestra.prompt_selected", "archestra.skill_created", "archestra.file_uploaded" ] }, "timestampMs": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 8, "maxLength": 64 }, "previousSessionId": { "type": "string", "minLength": 8, "maxLength": 64 }, "attributes": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "name", "timestampMs", "sessionId" ] } } }, "required": [ "events" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "number" } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/service-accounts/{id}/federated-credentials": { "get": { "operationId": "getServiceAccountFederatedCredentials", "tags": [ "Service Accounts" ], "description": "List a service account's federated credentials: the OIDC issuers, audiences, subjects and claims whose tokens can be exchanged for a short-lived token of the account\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "subject": { "type": "string" }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "serviceAccountId", "name", "issuer", "audience", "subject", "claimConditions", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "post": { "operationId": "createServiceAccountFederatedCredential", "tags": [ "Service Accounts" ], "description": "Add a federated credential to a service account. Tokens from the issuer whose audience, subject and listed claims all match exactly can then be exchanged at /api/workload-identity/token.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "issuer": { "type": "string", "maxLength": 2048 }, "audience": { "type": "string", "minLength": 1, "maxLength": 1024 }, "subject": { "type": "string", "minLength": 1, "maxLength": 1024 }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "required": [ "name", "issuer", "audience", "subject" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "subject": { "type": "string" }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "serviceAccountId", "name", "issuer", "audience", "subject", "claimConditions", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/service-accounts/{id}/federated-credentials/{credentialId}": { "patch": { "operationId": "updateServiceAccountFederatedCredential", "tags": [ "Service Accounts" ], "description": "Update a federated credential. Changing its issuer, audience, subject or claims revokes the tokens it already issued.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "issuer": { "type": "string", "maxLength": 2048 }, "audience": { "type": "string", "minLength": 1, "maxLength": 1024 }, "subject": { "type": "string", "minLength": 1, "maxLength": 1024 }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "credentialId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "subject": { "type": "string" }, "claimConditions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "lastUsedAt": { "nullable": true, "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "serviceAccountId", "name", "issuer", "audience", "subject", "claimConditions", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } }, "delete": { "operationId": "deleteServiceAccountFederatedCredential", "tags": [ "Service Accounts" ], "description": "Delete a federated credential. Tokens it issued stop working at once.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "credentialId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-identity/spiffe/.well-known/openid-configuration": { "get": { "operationId": "getSpiffeDiscoveryDocument", "tags": [ "Agent Identity" ], "description": "OIDC discovery document of the issuer of agents' SPIFFE JWT-SVIDs. Point a verifier that trusts OIDC issuers here.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "jwks_uri": { "type": "string" }, "id_token_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "subject_types_supported": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuer", "jwks_uri", "id_token_signing_alg_values_supported", "response_types_supported", "subject_types_supported" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-identity/spiffe/keys": { "get": { "operationId": "getSpiffeJwks", "tags": [ "Agent Identity" ], "description": "Public keys that sign agents' SPIFFE JWT-SVIDs, as a JSON Web Key Set.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "keys" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/agent-identity/spiffe/bundle": { "get": { "operationId": "getSpiffeTrustBundle", "tags": [ "Agent Identity" ], "description": "SPIFFE trust bundle of the agents' trust domain, for SPIFFE federation (https_web profile).\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "spiffe_refresh_hint": { "type": "number" } }, "required": [ "keys", "spiffe_refresh_hint" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_validation_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authentication_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_authorization_error" ] }, "internal_code": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_not_found_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_conflict_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string", "enum": [ "api_internal_server_error" ] }, "internal_code": { "type": "string" } }, "required": [ "message", "type" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } }, "/api/workload-identity/token": { "post": { "operationId": "exchangeWorkloadIdentityToken", "tags": [ "Service Accounts" ], "description": "Exchange an OIDC token from a workload's own identity provider (GitHub Actions, GitLab CI, Kubernetes, Google) for a short-lived token that acts as a service account (RFC 8693). Send grant_type urn:ietf:params:oauth:grant-type:token-exchange, subject_token_type urn:ietf:params:oauth:token-type:jwt, the token as subject_token, and service_account_id, form-encoded or as JSON. The token must match one of the account's federated credentials exactly. The issued token expires after one hour and carries the account's roles.\n\nAuthentication:\n\nRequired. Use an authenticated browser session or send your Archestra API key in the `Authorization` header.\n\nAuthorization:\n\nNone (no additional RBAC permission required)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "maxLength": 256 }, "subject_token": { "type": "string", "maxLength": 16384 }, "subject_token_type": { "type": "string", "maxLength": 256 }, "requested_token_type": { "type": "string", "maxLength": 256 }, "service_account_id": { "type": "string", "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "issued_token_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:access_token" ] }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } }, "required": [ "access_token", "issued_token_type", "token_type", "expires_in" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_grant", "unsupported_grant_type", "rate_limited", "server_error" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_grant", "unsupported_grant_type", "rate_limited", "server_error" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_grant", "unsupported_grant_type", "rate_limited", "server_error" ] }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ], "additionalProperties": false } } } } }, "x-required-permissions": { "kind": "none", "note": "None (no additional RBAC permission required)", "permissions": [] } } } } }